@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/bitmap-assets.js

@@ -1,60 +1,69 @@
-import { parseResourceVariantId, assetRelativePath } from "./resource-variant.js";
+import { assetRelativePath, parseLegacyResourceVariantId, parseResourceVariantId, } from "./resource-variant.js";
 function normalizeArchivePath(rel) {
-    return rel.replace(/\\/g, "/").replace(/^\.\//, "");
+    return rel.replace(/^\.\//, "");
 }
 /**
- * Identify a bitmap file inside a free/pro archive by parsing a directory
- * segment as resourceVariantId (G2, from the right). Never scans for a mid-path `-3d`.
+ * Identify a bitmap file at its canonical archive location
+ * `assets/<resourceVariantId>/<iconId>.<format>`. v2 uses controlled keyword
+ * tokens; v1 uses the explicit legacy `<group>-<format>-<size>` branch.
  */
-export function matchArchiveBitmapFile(archivePath) {
+export function matchArchiveBitmapFile(archivePath, options = {}) {
+    const mediaContractVersion = options.mediaContractVersion ?? 2;
+    if (archivePath.includes("\\"))
+        return undefined;
     const cleaned = normalizeArchivePath(archivePath);
-    const parts = cleaned.split("/").filter(Boolean);
-    if (parts.length < 2)
+    const parts = cleaned.split("/");
+    if (parts.length !== 3 || parts[0] !== "assets")
         return undefined;
-    const file = parts[parts.length - 1] ?? "";
+    const file = parts[2] ?? "";
     const dot = file.lastIndexOf(".");
     if (dot <= 0)
         return undefined;
     const format = file.slice(dot + 1);
     const iconId = file.slice(0, dot);
-    if (!iconId || iconId.includes(".."))
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(iconId))
+        return undefined;
+    try {
+        const variant = mediaContractVersion === 1
+            ? parseLegacyResourceVariantId(parts[1] ?? "")
+            : parseResourceVariantId(parts[1] ?? "");
+        if (variant.format !== format)
+            return undefined;
+        return { variant, iconId };
+    }
+    catch {
         return undefined;
-    for (let i = 0; i < parts.length - 1; i += 1) {
-        const segment = parts[i] ?? "";
-        try {
-            const variant = parseResourceVariantId(segment);
-            if (variant.format !== format)
-                continue;
-            return { variant, iconId };
-        }
-        catch {
-            continue;
-        }
     }
-    return undefined;
 }
 /**
  * Keep only archive files that belong to the requested variants and selected
  * icons. Other sizes/formats stay in the tarball/cache and are not written.
  */
-export function selectBitmapVariantAssets(archiveFiles, variants, iconIds) {
+export function selectBitmapVariantAssets(archiveFiles, variants, iconIds, options = {}) {
     const wanted = new Map(variants.map((variant) => [variant.resourceVariantId, variant]));
     const iconSet = new Set(iconIds);
+    const pairs = options.requestedPairs ?? variants.flatMap((variant) => iconIds.map((iconId) => ({ variantId: variant.resourceVariantId, iconId })));
+    const wantedPairs = new Set(pairs.map((pair) => `${pair.variantId}\0${pair.iconId}`));
     const skipped = [];
     const chosen = new Map();
+    const errors = [];
     for (const [archivePath, bytes] of Object.entries(archiveFiles)) {
-        const matched = matchArchiveBitmapFile(archivePath);
+        const matched = matchArchiveBitmapFile(archivePath, options);
         if (!matched)
             continue;
         if (!wanted.has(matched.variant.resourceVariantId)) {
             skipped.push(archivePath);
             continue;
         }
-        if (!iconSet.has(matched.iconId)) {
+        if (!iconSet.has(matched.iconId) || !wantedPairs.has(`${matched.variant.resourceVariantId}\0${matched.iconId}`)) {
             skipped.push(archivePath);
             continue;
         }
         const destRel = assetRelativePath(matched.variant.resourceVariantId, matched.iconId, matched.variant.format);
+        if (chosen.has(destRel)) {
+            errors.push(`duplicate bitmap asset for "${destRel}"`);
+            continue;
+        }
         chosen.set(destRel, {
             destRel,
             bytes,
@@ -62,13 +71,13 @@ export function selectBitmapVariantAssets(archiveFiles, variants, iconIds) {
             iconId: matched.iconId,
         });
     }
-    const errors = [];
-    for (const variant of variants) {
-        for (const iconId of iconIds) {
-            const destRel = assetRelativePath(variant.resourceVariantId, iconId, variant.format);
-            if (!chosen.has(destRel)) {
-                errors.push(`bitmap asset missing for icon "${iconId}" variant "${variant.resourceVariantId}"`);
-            }
+    for (const pair of pairs) {
+        const variant = wanted.get(pair.variantId);
+        if (!variant)
+            continue;
+        const destRel = assetRelativePath(variant.resourceVariantId, pair.iconId, variant.format);
+        if (!chosen.has(destRel)) {
+            errors.push(`bitmap asset missing for icon "${pair.iconId}" variant "${variant.resourceVariantId}"`);
         }
     }
     if (errors.length > 0)

package/dist/core/bitmap-shard-budget.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DEV-G08 (DEC-101/104/107): frozen bitmap shard resource budget interface.
+ *
+ * Values are calibrated from the OPS-04-06 real v4 release measurement
+ * (release 0.0.17, six bitmap shards):
+ *   - 512x512/png: 93,843,123 compressed / 94,408,209 expanded (largest)
+ *   - 256x256/png: 25,539,799 / 25,620,204
+ *   - 128x128/png:  7,792,540 /  7,828,646
+ *   - 512x512/webp: 8,668,836 /  8,932,948
+ *   - 256x256/webp: 3,575,782 /  3,800,040
+ *   - 128x128/webp: 1,599,168 /  1,829,146
+ * The largest single icon payload was 338,828 B and the aggregate six-shard
+ * download was 141,019,248 B. `compressedBytes`/`expandedBytes` therefore allow
+ * the measured 89.5/90.0 MiB worst case with headroom; `AUD-FIX-30` records the
+ * production freeze. No consumer may invent its own limit — every shard
+ * download/expand path takes its numbers from here, and the legacy
+ * `ICON_ARCHIVE_MAX_EXPANDED_BYTES` 512 MiB aggregate cap is deliberately not a
+ * shard budget.
+ */
+export interface BitmapShardBudget {
+    /** Largest signed compressed shard archive accepted for one tuple. */
+    readonly compressedBytes: number;
+    /** Largest expanded (uncompressed) shard archive accepted. */
+    readonly expandedBytes: number;
+    /** Largest number of archive entries (manifest + icons) in one shard. */
+    readonly entries: number;
+    /** Largest single uncompressed icon payload accepted. */
+    readonly singleFileBytes: number;
+    /** Largest aggregate downloaded bytes for one generate/install resolve. */
+    readonly totalDownloadBytes: number;
+    /** Reserved temporary disk headroom for staging one shard at a time. */
+    readonly tempDiskBytes: number;
+    /** Frozen concurrency; shards are always fetched one at a time. */
+    readonly concurrency: 1;
+    /** Per-shard descriptor request timeout. */
+    readonly descriptorTimeoutMs: number;
+    /** Per-shard payload download timeout. */
+    readonly downloadTimeoutMs: number;
+}
+export declare const BITMAP_SHARD_BUDGET: BitmapShardBudget;
+/** Backwards-compatible aliases kept for the frozen shard contract. */
+export declare const BITMAP_SHARD_MAX_ENTRIES: number;
+export declare const BITMAP_SHARD_MAX_EXPANDED_BYTES: number;

package/dist/core/bitmap-shard-budget.js

@@ -0,0 +1,16 @@
+export const BITMAP_SHARD_BUDGET = Object.freeze({
+    compressedBytes: 128 * 1024 * 1024,
+    expandedBytes: 128 * 1024 * 1024,
+    entries: 2000,
+    singleFileBytes: 16 * 1024 * 1024,
+    totalDownloadBytes: 512 * 1024 * 1024,
+    tempDiskBytes: 256 * 1024 * 1024,
+    concurrency: 1,
+    descriptorTimeoutMs: 5_000,
+    // The largest measured production shard is about 94 MiB. A one-minute
+    // timeout rejects healthy downloads below roughly 13 Mbit/s.
+    downloadTimeoutMs: 120_000,
+});
+/** Backwards-compatible aliases kept for the frozen shard contract. */
+export const BITMAP_SHARD_MAX_ENTRIES = BITMAP_SHARD_BUDGET.entries;
+export const BITMAP_SHARD_MAX_EXPANDED_BYTES = BITMAP_SHARD_BUDGET.expandedBytes;

package/dist/core/bitmap-shard-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * W2-A/A3: the CLI's global bitmap-shard resource cache.
+ *
+ * The CLI caches bitmap shards under `<cacheDir>/bitmap-shards/<version>/...`
+ * and records exactly what it holds in a manifest (`bitmap-shards/manifest.json`)
+ * so a later install can compute what is missing without touching the network.
+ * The default warm-up set is the SVG/free package plus every bitmap style
+ * group's `128/webp` shard; larger sizes or the `png` format are downloaded
+ * on demand (W2-B) when the project config asks for them.
+ */
+import { type CacheIo } from "./cache.js";
+import type { IconCatalog } from "../catalog/catalog.js";
+import { type BitmapShard, type BitmapShardFormat } from "./bitmap-shards.js";
+import { type BitmapShardFetchProgress, type BitmapShardTuple, type FetchBitmapShardsDeps } from "./bitmap-shard-resolver.js";
+export declare const BITMAP_SHARD_CACHE_SCHEMA_VERSION = 1;
+/** W2-A1: the default, always-warmed resource set. */
+export declare const DEFAULT_WARMUP_SIZE = 128;
+export declare const DEFAULT_WARMUP_FORMAT: BitmapShardFormat;
+export interface BitmapShardCacheManifest {
+    readonly schemaVersion: 1;
+    readonly updatedAt: string;
+    readonly shards: readonly BitmapShard[];
+}
+export declare function bitmapShardCacheManifestPath(cacheDir: string): string;
+/**
+ * Tolerant read: a missing/corrupt manifest is treated as empty (the cache is
+ * additive and every cached entry is re-verified before use), never a crash.
+ */
+export declare function readBitmapShardCacheManifest(cacheDir: string, io: CacheIo): BitmapShardCacheManifest;
+/** Atomic, idempotent manifest write (verified bytes are staged then renamed). */
+export declare function writeBitmapShardCacheManifest(cacheDir: string, io: CacheIo, shards: readonly BitmapShard[], now?: number): void;
+/** Merge new pins over an existing manifest, keeping one entry per tuple@version. */
+export declare function mergeBitmapShardCacheManifest(manifest: BitmapShardCacheManifest, pins: readonly BitmapShard[]): BitmapShard[];
+/** W2-B2: tuples with no cached entry for the exact resource version. */
+export declare function missingBitmapShardTuples(manifest: BitmapShardCacheManifest, expected: readonly BitmapShardTuple[], version: string): BitmapShardTuple[];
+/**
+ * W2-A1: every bitmap style group's `128/webp` shard, in canonical order.
+ * Groups that do not ship the default variant are skipped (the config
+ * validator reports that explicitly when a user asks for them).
+ */
+export declare function defaultWarmupTuples(catalog: IconCatalog): BitmapShardTuple[];
+export interface WarmupPlan {
+    readonly tuples: readonly BitmapShardTuple[];
+    readonly missing: readonly BitmapShardTuple[];
+    readonly reused: number;
+}
+export interface WarmDefaultBitmapShardsDeps extends Omit<FetchBitmapShardsDeps, "existingPins"> {
+    readonly catalog: IconCatalog;
+    readonly cacheDir: string;
+    readonly io: CacheIo;
+    readonly now?: number;
+    /** Emitted once before any network request so the UI can print the plan. */
+    readonly onPlan?: (plan: WarmupPlan) => void;
+    /** W2-B6: per-tuple/byte progress forwarded from the shard fetch. */
+    readonly onProgress?: (event: BitmapShardFetchProgress) => void;
+}
+export interface WarmDefaultBitmapShardsResult {
+    readonly tuples: readonly BitmapShardTuple[];
+    readonly pins: readonly BitmapShard[];
+    readonly downloaded: number;
+    readonly reused: number;
+}
+/**
+ * W2-A2/B7: warm the default set into the cache. Already-cached shards are
+ * re-verified and reused without a network call; only missing tuples are
+ * fetched. The manifest is updated atomically after a fully verified fetch.
+ */
+export declare function warmDefaultBitmapShards(deps: WarmDefaultBitmapShardsDeps): Promise<WarmDefaultBitmapShardsResult>;

package/dist/core/bitmap-shard-cache.js

@@ -0,0 +1,115 @@
+/**
+ * W2-A/A3: the CLI's global bitmap-shard resource cache.
+ *
+ * The CLI caches bitmap shards under `<cacheDir>/bitmap-shards/<version>/...`
+ * and records exactly what it holds in a manifest (`bitmap-shards/manifest.json`)
+ * so a later install can compute what is missing without touching the network.
+ * The default warm-up set is the SVG/free package plus every bitmap style
+ * group's `128/webp` shard; larger sizes or the `png` format are downloaded
+ * on demand (W2-B) when the project config asks for them.
+ */
+import { join } from "node:path";
+import { cacheArtifact } from "./cache.js";
+import { isVariantAvailable } from "../generator/theme-resolve.js";
+import { buildResourceVariantId } from "./resource-variant.js";
+import { parseBitmapShard, sortBitmapShards, } from "./bitmap-shards.js";
+import { fetchSelectedBitmapShards, } from "./bitmap-shard-resolver.js";
+export const BITMAP_SHARD_CACHE_SCHEMA_VERSION = 1;
+/** W2-A1: the default, always-warmed resource set. */
+export const DEFAULT_WARMUP_SIZE = 128;
+export const DEFAULT_WARMUP_FORMAT = "webp";
+export function bitmapShardCacheManifestPath(cacheDir) {
+    return join(cacheDir, "bitmap-shards", "manifest.json");
+}
+function emptyManifest() {
+    return { schemaVersion: BITMAP_SHARD_CACHE_SCHEMA_VERSION, updatedAt: new Date(0).toISOString(), shards: [] };
+}
+/**
+ * Tolerant read: a missing/corrupt manifest is treated as empty (the cache is
+ * additive and every cached entry is re-verified before use), never a crash.
+ */
+export function readBitmapShardCacheManifest(cacheDir, io) {
+    const path = bitmapShardCacheManifestPath(cacheDir);
+    if (!io.existsSync(path) || !io.readFileSync)
+        return emptyManifest();
+    try {
+        const raw = JSON.parse(Buffer.from(io.readFileSync(path)).toString("utf8"));
+        if (raw.schemaVersion !== BITMAP_SHARD_CACHE_SCHEMA_VERSION || !Array.isArray(raw.shards))
+            return emptyManifest();
+        const shards = raw.shards.map(parseBitmapShard);
+        return {
+            schemaVersion: BITMAP_SHARD_CACHE_SCHEMA_VERSION,
+            updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : new Date(0).toISOString(),
+            shards: sortBitmapShards(shards),
+        };
+    }
+    catch {
+        return emptyManifest();
+    }
+}
+/** Atomic, idempotent manifest write (verified bytes are staged then renamed). */
+export function writeBitmapShardCacheManifest(cacheDir, io, shards, now = Date.now()) {
+    const body = `${JSON.stringify({ schemaVersion: BITMAP_SHARD_CACHE_SCHEMA_VERSION, updatedAt: new Date(now).toISOString(), shards: sortBitmapShards(shards) }, null, 2)}\n`;
+    cacheArtifact(io, bitmapShardCacheManifestPath(cacheDir), Buffer.from(body, "utf8"));
+}
+function tupleKey(shard) {
+    return `${shard.resourceVersion}/${shard.styleGroupId}/${shard.imageSize.width}x${shard.imageSize.height}/${shard.format}`;
+}
+/** Merge new pins over an existing manifest, keeping one entry per tuple@version. */
+export function mergeBitmapShardCacheManifest(manifest, pins) {
+    const byKey = new Map();
+    for (const shard of [...manifest.shards, ...pins])
+        byKey.set(tupleKey(shard), shard);
+    return sortBitmapShards([...byKey.values()]);
+}
+/** W2-B2: tuples with no cached entry for the exact resource version. */
+export function missingBitmapShardTuples(manifest, expected, version) {
+    const have = new Set(manifest.shards
+        .filter((shard) => shard.resourceVersion === version)
+        .map((shard) => tupleKey({ ...shard, resourceVersion: version })));
+    return expected.filter((tuple) => {
+        const key = `${version}/${tuple.styleGroupId}/${tuple.imageSize.width}x${tuple.imageSize.height}/${tuple.format}`;
+        return !have.has(key);
+    });
+}
+/**
+ * W2-A1: every bitmap style group's `128/webp` shard, in canonical order.
+ * Groups that do not ship the default variant are skipped (the config
+ * validator reports that explicitly when a user asks for them).
+ */
+export function defaultWarmupTuples(catalog) {
+    const imageSize = { width: DEFAULT_WARMUP_SIZE, height: DEFAULT_WARMUP_SIZE };
+    const tuples = [];
+    for (const group of catalog.styleGroups) {
+        if (group.type !== "bitmap")
+            continue;
+        const variantId = buildResourceVariantId(group.id, DEFAULT_WARMUP_FORMAT, DEFAULT_WARMUP_SIZE);
+        if (!isVariantAvailable(group, variantId))
+            continue;
+        tuples.push({ styleGroupId: group.id, imageSize, format: DEFAULT_WARMUP_FORMAT });
+    }
+    tuples.sort((a, b) => (a.styleGroupId < b.styleGroupId ? -1 : a.styleGroupId > b.styleGroupId ? 1 : 0));
+    return tuples;
+}
+/**
+ * W2-A2/B7: warm the default set into the cache. Already-cached shards are
+ * re-verified and reused without a network call; only missing tuples are
+ * fetched. The manifest is updated atomically after a fully verified fetch.
+ */
+export async function warmDefaultBitmapShards(deps) {
+    const tuples = defaultWarmupTuples(deps.catalog);
+    const manifest = readBitmapShardCacheManifest(deps.cacheDir, deps.io);
+    const missing = missingBitmapShardTuples(manifest, tuples, deps.version);
+    deps.onPlan?.({ tuples, missing, reused: tuples.length - missing.length });
+    if (tuples.length === 0)
+        return { tuples, pins: [], downloaded: 0, reused: 0 };
+    const existingPins = manifest.shards.filter((shard) => shard.resourceVersion === deps.version);
+    const fetched = await fetchSelectedBitmapShards(tuples, { ...deps, existingPins });
+    writeBitmapShardCacheManifest(deps.cacheDir, deps.io, mergeBitmapShardCacheManifest(manifest, fetched.pins), deps.now ?? Date.now());
+    return {
+        tuples,
+        pins: fetched.pins,
+        downloaded: fetched.shards.length,
+        reused: fetched.pins.length - fetched.shards.length,
+    };
+}

package/dist/core/bitmap-shard-download.d.ts

@@ -0,0 +1,130 @@
+/**
+ * BITMAP-SHARD-V1 (DEC-97..DEC-108): CLI shard descriptor fetch, direct-from-R2
+ * download, strict verification and atomic cached persistence.
+ *
+ * The bearer is only ever sent to the trusted API origin. The R2 shard download
+ * never forwards authorization/cookies (`downloadSignedArtifact`).
+ *
+ * Budget constants here are interim; `DEV-G08`/`OPS-05-05` freeze the final
+ * per-shard download/expand budgets after real measurement.
+ */
+import { type CacheIo } from "./cache.js";
+import { type SignedArtifactDescriptor } from "./signed-artifact.js";
+import { type BitmapShard, type BitmapShardFormat, type BitmapShardImageSize } from "./bitmap-shards.js";
+import { BITMAP_SHARD_MAX_ENTRIES, BITMAP_SHARD_MAX_EXPANDED_BYTES } from "./bitmap-shard-budget.js";
+export { BITMAP_SHARD_MAX_ENTRIES, BITMAP_SHARD_MAX_EXPANDED_BYTES };
+export declare const BITMAP_SHARD_DESCRIPTOR_URL = "https://api.moeicons.com/v1/icon-library/pro/bitmap-shard-descriptor";
+/**
+ * Only the fields that identify the immutable shard are required to verify
+ * cached bytes; a full descriptor additionally carries a signed URL/expiry.
+ */
+export interface BitmapShardVerificationTarget {
+    readonly version: string;
+    readonly styleGroupId: string;
+    readonly imageSize: BitmapShardImageSize;
+    readonly format: BitmapShardFormat;
+    readonly size: number;
+    readonly sha256: string;
+    readonly manifestSha256: string;
+}
+export interface BitmapShardCacheIdentity {
+    readonly version: string;
+    readonly styleGroupId: string;
+    readonly imageSize: BitmapShardImageSize;
+    readonly format: BitmapShardFormat;
+    readonly sha256: string;
+}
+export interface BitmapShardDescriptor extends SignedArtifactDescriptor, BitmapShardVerificationTarget {
+    readonly tier: "pro";
+    readonly descriptorSha256: string;
+    readonly filename: string;
+}
+/**
+ * Test seam: `MOEICONS_BITMAP_SHARD_DESCRIPTOR_URL` overrides the authenticated
+ * per-shard descriptor endpoint. Only https or loopback http is accepted, so a
+ * production endpoint can never be redirected by a stray environment variable
+ * to a plaintext or untrusted origin (mirrors the Pro descriptor seam).
+ */
+export declare function resolveBitmapShardDescriptorEndpoint(env: Readonly<Record<string, string | undefined>>): {
+    readonly url: string;
+    readonly allowLoopback: boolean;
+};
+export declare function parseBitmapShardDescriptor(value: unknown, now: number, options?: {
+    readonly allowLoopback?: boolean;
+}): BitmapShardDescriptor;
+/**
+ * POST one tuple to the trusted API. Bearer is never sent to R2. The request is
+ * bounded by `BITMAP_SHARD_BUDGET.descriptorTimeoutMs` unless overridden, and
+ * honors an external cancellation signal (DEV-G08).
+ */
+export declare function fetchBitmapShardDescriptor(tuple: {
+    readonly version: string;
+    readonly descriptorSha256: string;
+    readonly styleGroupId: string;
+    readonly imageSize: BitmapShardImageSize;
+    readonly format: BitmapShardFormat;
+}, accessToken: string, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly now?: number;
+    readonly allowLoopback?: boolean;
+    readonly endpoint?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}): Promise<BitmapShardDescriptor>;
+export interface VerifiedBitmapShard {
+    readonly descriptor: BitmapShardDescriptor;
+    /** `icons/<iconId>.<format>` -> bytes. */
+    readonly files: Readonly<Record<string, Uint8Array>>;
+    readonly iconIds: readonly string[];
+}
+/** An offline-verified shard loaded from the cache; the URL/expiry is irrelevant. */
+export interface CachedBitmapShard {
+    readonly target: BitmapShardVerificationTarget;
+    readonly files: Readonly<Record<string, Uint8Array>>;
+    readonly iconIds: readonly string[];
+}
+/** DEC-101 verification of downloaded shard bytes against the full descriptor. */
+export declare function verifyBitmapShardArchive(bytes: Uint8Array, descriptor: BitmapShardVerificationTarget): VerifiedBitmapShard;
+/** Unambiguous cache identity (DEC-101). */
+export declare function bitmapShardCacheKey(identity: BitmapShardCacheIdentity): string;
+export declare function bitmapShardCachePath(cacheDir: string, identity: BitmapShardCacheIdentity): string;
+/**
+ * Offline/pin path: load one shard from the local cache and re-verify its
+ * identity, size, SHA, manifest digest, icon set and dimensions. A missing or
+ * partial cache fails closed; a poisoned cache fails digest verification.
+ */
+export declare function loadCachedBitmapShard(target: BitmapShardVerificationTarget, cacheDir: string, io: CacheIo): CachedBitmapShard;
+/** Reconstruct the offline verification identity pinned in install metadata. */
+export declare function bitmapShardVerificationTargetFromPin(pin: {
+    readonly resourceVersion: string;
+    readonly styleGroupId: string;
+    readonly imageSize: BitmapShardImageSize;
+    readonly format: BitmapShardFormat;
+    readonly compressedSize: number;
+    readonly sha256: string;
+    readonly manifestSha256: string;
+}): BitmapShardVerificationTarget;
+/** Build the canonical pin identity from a freshly verified download. */
+export declare function bitmapShardPinFromVerified(verified: VerifiedBitmapShard): BitmapShard;
+/**
+ * Download directly from the private R2 signed host and atomically cache the
+ * verified archive. Any size/SHA/manifest/dimension drift fails closed.
+ */
+export declare function downloadAndCacheBitmapShard(descriptor: BitmapShardDescriptor, deps: {
+    readonly cacheDir: string;
+    readonly io: CacheIo;
+    readonly fetch?: typeof fetch;
+    readonly allowedHosts?: readonly string[];
+    readonly now?: number;
+    readonly allowLoopback?: boolean;
+    readonly signal?: AbortSignal;
+    readonly statfs?: (dir: string) => {
+        readonly availableBytes: number;
+    } | undefined;
+    readonly timeoutMs?: number;
+    /** W2-B6: byte-level progress for a single shard payload. */
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}): Promise<VerifiedBitmapShard>;