@aiwg/cli 2026.7.19 → 2026.7.21

package/dist/src/resources/doctor.js

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getResourceCacheRoot, readVerifiedRegularFile } from "./web-release.js";
+import { readResourceLockfile, resourceLockfilePath } from "./lockfile.js";
+const MAX_RELEASE_MANIFEST_BYTES = 4 * 1024 * 1024;
+function mark(severity) {
+    if (severity === "ok")
+        return "✓";
+    if (severity === "info")
+        return "•";
+    if (severity === "warning")
+        return "⚠";
+    return "✗";
+}
+function cacheGenerationDir(cacheRoot, version, manifestSha256) {
+    return path.join(cacheRoot, "releases", version, manifestSha256);
+}
+function isRealDirectory(pathname) {
+    try {
+        const stat = fs.lstatSync(pathname);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function buildWebResourceDoctorSection(projectDir, options = {}) {
+    const diagnostics = [];
+    const cacheRoot = getResourceCacheRoot(options.cacheRoot);
+    let lockfile;
+    try {
+        lockfile = readResourceLockfile(projectDir);
+    }
+    catch (error) {
+        diagnostics.push({
+            severity: "error",
+            code: "resource-lockfile-invalid",
+            message: `${resourceLockfilePath(projectDir)} is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    if (!lockfile) {
+        diagnostics.push({
+            severity: "info",
+            code: "resource-lockfile-missing",
+            message: `No ${resourceLockfilePath(projectDir)} found; web resource source mode is not pinned for this project.`,
+        });
+    }
+    else {
+        for (const [key, resource] of Object.entries(lockfile.resources)) {
+            diagnostics.push({
+                severity: "info",
+                code: "resource-source-mode",
+                message: `${key}: source=${resource.source}, selector=${resource.selector}, resolved=${resource.version}, manifest=${resource.manifestSha256}`,
+            });
+            const generationDir = cacheGenerationDir(cacheRoot, resource.version, resource.manifestSha256);
+            if (!isRealDirectory(generationDir)) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "resource-cache-miss",
+                    message: `${key}: locked release ${resource.version}/${resource.manifestSha256} is not present in ${cacheRoot}; run the pinned versions command once online to warm the cache.`,
+                });
+                continue;
+            }
+            try {
+                readVerifiedRegularFile(path.join(generationDir, "manifest.json"), {
+                    label: `${key} locked resource manifest`,
+                    maxBytes: MAX_RELEASE_MANIFEST_BYTES,
+                    expectedSha256: resource.manifestSha256,
+                });
+                readVerifiedRegularFile(path.join(generationDir, "raw", "prebuilt", "fortemi-core", "framework", "manifest.json"), {
+                    label: `${key} locked Fortemi Core manifest`,
+                    maxBytes: MAX_RELEASE_MANIFEST_BYTES,
+                    expectedSize: resource.fortemiCore.manifestSize,
+                    expectedSha256: resource.fortemiCore.manifestSha256,
+                });
+                readVerifiedRegularFile(path.join(generationDir, "raw", "prebuilt", "fortemi-core", "framework", "aiwg-fortemi-index-v2.json"), {
+                    label: `${key} locked Fortemi Core export`,
+                    maxBytes: resource.fortemiCore.exportSize,
+                    expectedSize: resource.fortemiCore.exportSize,
+                    expectedSha256: resource.fortemiCore.exportSha256,
+                });
+                diagnostics.push({
+                    severity: "ok",
+                    code: "resource-cache-verified",
+                    message: `${key}: locked release cache is warm and digest-verified.`,
+                });
+            }
+            catch (error) {
+                diagnostics.push({
+                    severity: "error",
+                    code: "resource-cache-drift",
+                    message: `${key}: locked release cache drift detected: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+    }
+    const lines = ["\n── Web resource cache ──"];
+    for (const diagnostic of diagnostics) {
+        lines.push(`  ${mark(diagnostic.severity)} ${diagnostic.message}`);
+    }
+    return {
+        output: lines.join("\n"),
+        diagnostics,
+        hasFailures: diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/src/resources/lockfile.js

@@ -0,0 +1,125 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { projectAiwgPath, resolveProjectAiwgDir } from "../config/project-artifacts.js";
+export const RESOURCE_LOCKFILE_SCHEMA = "aiwg.resources-lock/v1";
+export const RESOURCE_LOCKFILE_NAME = "resources.lock.json";
+export const DEFAULT_RESOURCE_LOCK_KEY = "framework";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateLockedResource(value, key) {
+    if (!isRecord(value))
+        throw new Error(`resource lock entry '${key}' must be an object`);
+    if (value.source !== "web")
+        throw new Error(`resource lock entry '${key}' has an unsupported source`);
+    for (const field of ["selector", "selectorKind", "version", "manifestUrl", "baseUrl", "manifestSha256", "lockedAt"]) {
+        if (typeof value[field] !== "string")
+            throw new Error(`resource lock entry '${key}' has an invalid ${field}`);
+    }
+    if (value.selectorKind !== "exact" &&
+        value.selectorKind !== "channel" &&
+        value.selectorKind !== "range" &&
+        value.selectorKind !== "digest") {
+        throw new Error(`resource lock entry '${key}' has an invalid selectorKind`);
+    }
+    if (typeof value.descriptorCount !== "number" || !Number.isSafeInteger(value.descriptorCount) || value.descriptorCount < 0) {
+        throw new Error(`resource lock entry '${key}' has an invalid descriptorCount`);
+    }
+    if (value.channelSequence !== undefined && (typeof value.channelSequence !== "number" ||
+        !Number.isSafeInteger(value.channelSequence) ||
+        value.channelSequence < 1)) {
+        throw new Error(`resource lock entry '${key}' has an invalid channelSequence`);
+    }
+    if (!isRecord(value.fortemiCore))
+        throw new Error(`resource lock entry '${key}' has invalid fortemiCore metadata`);
+    const fortemiCore = value.fortemiCore;
+    for (const field of ["manifestSha256", "exportSha256"]) {
+        if (typeof fortemiCore[field] !== "string") {
+            throw new Error(`resource lock entry '${key}' has an invalid fortemiCore.${field}`);
+        }
+    }
+    for (const field of ["manifestSize", "exportSize"]) {
+        if (typeof fortemiCore[field] !== "number" || !Number.isSafeInteger(fortemiCore[field]) || fortemiCore[field] < 0) {
+            throw new Error(`resource lock entry '${key}' has an invalid fortemiCore.${field}`);
+        }
+    }
+    return value;
+}
+export function resourceLockfilePath(projectDir) {
+    return projectAiwgPath(projectDir, RESOURCE_LOCKFILE_NAME);
+}
+export function releaseToLockedWebResource(release, now = new Date()) {
+    return {
+        source: "web",
+        selector: release.selector,
+        selectorKind: release.selectorKind,
+        version: release.version,
+        manifestUrl: release.manifestUrl,
+        baseUrl: release.baseUrl,
+        manifestSha256: release.manifestDigest,
+        ...(release.channelSequence === undefined ? {} : { channelSequence: release.channelSequence }),
+        fortemiCore: {
+            manifestSha256: release.fortemiManifestSha256,
+            manifestSize: release.fortemiManifestSize,
+            exportSha256: release.fortemiExportSha256,
+            exportSize: release.fortemiExportSize,
+        },
+        descriptorCount: release.descriptors.size,
+        lockedAt: now.toISOString(),
+    };
+}
+export function readResourceLockfile(projectDir) {
+    const pathname = resourceLockfilePath(projectDir);
+    if (!fs.existsSync(pathname))
+        return null;
+    const parsed = JSON.parse(fs.readFileSync(pathname, "utf8"));
+    if (!isRecord(parsed) || parsed.schemaVersion !== RESOURCE_LOCKFILE_SCHEMA) {
+        throw new Error(`${RESOURCE_LOCKFILE_NAME} has an unsupported schemaVersion`);
+    }
+    if (typeof parsed.generatedAt !== "string") {
+        throw new Error(`${RESOURCE_LOCKFILE_NAME} has an invalid generatedAt`);
+    }
+    if (!isRecord(parsed.resources)) {
+        throw new Error(`${RESOURCE_LOCKFILE_NAME} has an invalid resources object`);
+    }
+    const resources = {};
+    for (const [key, value] of Object.entries(parsed.resources)) {
+        resources[key] = validateLockedResource(value, key);
+    }
+    return {
+        schemaVersion: RESOURCE_LOCKFILE_SCHEMA,
+        generatedAt: parsed.generatedAt,
+        resources,
+    };
+}
+export function writeWebResourceLock(projectDir, release, options = {}) {
+    const key = options.key ?? DEFAULT_RESOURCE_LOCK_KEY;
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(key))
+        throw new Error(`Invalid resource lock key: ${key}`);
+    const now = options.now ?? new Date();
+    const existing = readResourceLockfile(projectDir);
+    const entry = releaseToLockedWebResource(release, now);
+    const lockfile = {
+        schemaVersion: RESOURCE_LOCKFILE_SCHEMA,
+        generatedAt: now.toISOString(),
+        resources: {
+            ...(existing?.resources ?? {}),
+            [key]: entry,
+        },
+    };
+    const dir = resolveProjectAiwgDir(projectDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const pathname = path.join(dir, RESOURCE_LOCKFILE_NAME);
+    const tmpPath = `${pathname}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(lockfile, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+        fs.renameSync(tmpPath, pathname);
+    }
+    catch (error) {
+        fs.rmSync(tmpPath, { force: true });
+        throw error;
+    }
+    return { path: pathname, lockfile, entry };
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/src/resources/resolver.js

@@ -0,0 +1,133 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fetchVerifiedRawResource, resolveWebRelease, } from "./web-release.js";
+function assertSafeSegment(value, label) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value) || value === "." || value === "..") {
+        throw new Error(`${label} is not a safe AIWG resource segment`);
+    }
+}
+function assertSafeRelativePath(value) {
+    if (value.length === 0 ||
+        value.startsWith("/") ||
+        value.includes("\\") ||
+        value.split("/").some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error("AIWG logical resource path is not safe");
+    }
+    for (const part of value.split("/"))
+        assertSafeSegment(part, "AIWG logical resource path segment");
+}
+export function parseAiwgResourceId(logicalId) {
+    let url;
+    try {
+        url = new URL(logicalId);
+    }
+    catch {
+        throw new Error(`Invalid AIWG logical resource ID: ${logicalId}`);
+    }
+    if (url.protocol !== "aiwg:")
+        throw new Error(`Unsupported AIWG logical resource protocol: ${url.protocol}`);
+    if (url.search || url.hash || url.username || url.password) {
+        throw new Error("AIWG logical resource IDs must not include auth, query, or fragment components");
+    }
+    const namespace = url.hostname;
+    const parts = url.pathname.split("/").filter(Boolean);
+    let relativePath;
+    if (namespace === "frameworks") {
+        const [name, ...rest] = parts;
+        if (!name || rest.length === 0)
+            throw new Error("Framework resource IDs require a name and path");
+        assertSafeSegment(name, "framework name");
+        const suffix = rest.join("/");
+        assertSafeRelativePath(suffix);
+        relativePath = `agentic/code/frameworks/${name}/${suffix}`;
+    }
+    else if (namespace === "addons") {
+        const [name, ...rest] = parts;
+        if (!name || rest.length === 0)
+            throw new Error("Addon resource IDs require a name and path");
+        assertSafeSegment(name, "addon name");
+        const suffix = rest.join("/");
+        assertSafeRelativePath(suffix);
+        relativePath = `agentic/code/addons/${name}/${suffix}`;
+    }
+    else if (namespace === "core") {
+        if (parts.length < 2)
+            throw new Error("Core resource IDs require a kind and path");
+        const [kind, ...rest] = parts;
+        assertSafeSegment(kind, "core resource kind");
+        const suffix = rest.join("/");
+        assertSafeRelativePath(suffix);
+        relativePath = `agentic/code/${kind}/${suffix}`;
+    }
+    else {
+        throw new Error(`Unsupported AIWG logical resource namespace: ${namespace}`);
+    }
+    return {
+        logicalId,
+        relativePath,
+        rawPath: `raw/${relativePath}`,
+    };
+}
+export function logicalIdFromFirstPartyPath(indexedPath) {
+    const normalized = indexedPath.replace(/\\/g, "/").replace(/^raw\//, "").replace(/^\/+/, "");
+    const parts = normalized.split("/");
+    if (parts[0] !== "agentic" || parts[1] !== "code")
+        return null;
+    if ((parts[2] === "frameworks" || parts[2] === "addons") && parts.length > 4) {
+        return `aiwg://${parts[2]}/${parts[3]}/${parts.slice(4).join("/")}`;
+    }
+    if (parts.length > 3)
+        return `aiwg://core/${parts[2]}/${parts.slice(3).join("/")}`;
+    return null;
+}
+async function readLocalResource(parsed, frameworkRoot) {
+    const root = path.resolve(frameworkRoot);
+    const pathname = path.resolve(root, parsed.relativePath);
+    if (!pathname.startsWith(`${root}${path.sep}`))
+        throw new Error("AIWG local resource resolved outside the framework root");
+    return fs.readFile(pathname);
+}
+export async function resolveAiwgResourceBytes(logicalId, options) {
+    const parsed = parseAiwgResourceId(logicalId);
+    const requestedSource = options.source ?? "local";
+    const diagnostics = [];
+    if (requestedSource === "local" || requestedSource === "auto") {
+        try {
+            const bytes = await readLocalResource(parsed, options.frameworkRoot);
+            diagnostics.push(`source=${requestedSource === "auto" ? "auto(local)" : "local"}`);
+            return {
+                logicalId,
+                source: "local",
+                path: path.resolve(options.frameworkRoot, parsed.relativePath),
+                bytes,
+                diagnostics,
+            };
+        }
+        catch (error) {
+            if (requestedSource === "local")
+                throw error;
+            diagnostics.push(`local-miss=${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const webRelease = options.webRelease ?? await resolveWebRelease({
+        ...options.webReleaseOptions,
+        selector: options.selector ?? "stable",
+        offline: options.offline,
+    });
+    const bytes = await fetchVerifiedRawResource(webRelease, parsed.rawPath, {
+        baseUrl: options.webReleaseOptions?.baseUrl,
+        fetcher: options.webReleaseOptions?.fetcher,
+        allowInsecureLoopbackHttp: options.webReleaseOptions?.allowInsecureLoopbackHttp,
+        offline: options.offline,
+    });
+    diagnostics.push(`source=${requestedSource === "auto" ? "auto(web)" : "web"}`);
+    return {
+        logicalId,
+        source: "web",
+        path: parsed.rawPath,
+        bytes,
+        webRelease,
+        diagnostics,
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/src/resources/web-release.d.ts

@@ -7,6 +7,14 @@ export type ResourceSelector = {
 } | {
     kind: "channel";
     value: string;
+} | {
+    kind: "range";
+    value: string;
+    normalizedRange: string;
+} | {
+    kind: "digest";
+    value: string;
+    digest: string;
 };
 export interface ResourceFetchResponse {
     ok: boolean;

package/dist/src/resources/web-release.js

@@ -2,6 +2,7 @@ import { createHash, createPublicKey, randomUUID, verify } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import semver from "semver";
 export const DEFAULT_RESOURCE_BASE_URL = "https://releases.aiwg.io";
 export const AIWG_RELEASE_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
 MCowBQYDK2VwAyEA8BsJ2vjuHBReexz328sknfL7MKUtxynX6MGfqFVMD38=
@@ -9,6 +10,7 @@ MCowBQYDK2VwAyEA8BsJ2vjuHBReexz328sknfL7MKUtxynX6MGfqFVMD38=
 const EXACT_VERSION_PATTERN = /^(?:19|20)\d{2}\.(?:[1-9]|1[0-2])\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
 const CHANNEL_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const DIGEST_SELECTOR_PATTERN = /^sha256:([0-9a-f]{64})$/;
 const SIGNATURE_PATTERN = /^(?:[A-Za-z0-9+/]{4}){21}(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)$/;
 const RELEASE_MANIFEST_SCHEMAS = new Set([
     "aiwg.resource-manifest/v1",
@@ -23,6 +25,8 @@ const MAX_SIGNATURE_BYTES = 64 * 1024;
 const MAX_COMPLETION_MARKER_BYTES = 4 * 1024;
 const MAX_CHANNEL_CACHE_CANDIDATES = 128;
 const MAX_RELEASE_CACHE_CANDIDATES = 32;
+const MAX_VERSION_INDEX_BYTES = 4 * 1024 * 1024;
+const MAX_VERSION_INDEX_ENTRIES = 2048;
 // A cold lightweight-CLI install downloads the signed release manifest
 // (~2 MiB) and Fortemi export (~11 MiB today). Fifteen seconds proved too
 // aggressive on otherwise healthy container and remote-network paths. Keep a
@@ -85,12 +89,24 @@ export function verifySignedResourceBytes(bytes, signatureBytes, publicKeyPem =
     return digest;
 }
 export function parseResourceSelector(selector) {
+    if (selector.trim() !== selector || selector.length === 0 || /^v\d/.test(selector)) {
+        throw new Error(`Unsupported AIWG resource selector '${selector}'. This release supports exact calendar-semver versions, SemVer ranges, sha256 manifest digests, or channel names.`);
+    }
     if (EXACT_VERSION_PATTERN.test(selector))
         return { kind: "exact", value: selector };
+    const digestMatch = DIGEST_SELECTOR_PATTERN.exec(selector);
+    if (digestMatch)
+        return { kind: "digest", value: selector, digest: digestMatch[1] };
     if (CHANNEL_PATTERN.test(selector) && !/^v\d/.test(selector)) {
         return { kind: "channel", value: selector };
     }
-    throw new Error(`Unsupported AIWG resource selector '${selector}'. This release supports exact calendar-semver versions or channel names only.`);
+    const normalizedRange = semver.validRange(selector, { includePrerelease: true });
+    const explicitRange = /[<>=~^*xX|\s]/.test(selector);
+    const versionLikeTokens = selector.match(/\b(?:19|20)\d{2}\.\d+\.\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?\b/g) ?? [];
+    const calendarVersionTokens = versionLikeTokens.every((token) => EXACT_VERSION_PATTERN.test(token));
+    if (normalizedRange && explicitRange && calendarVersionTokens)
+        return { kind: "range", value: selector, normalizedRange };
+    throw new Error(`Unsupported AIWG resource selector '${selector}'. This release supports exact calendar-semver versions, SemVer ranges, sha256 manifest digests, or channel names.`);
 }
 function assertSafeRelativePath(value, label) {
     if (typeof value !== "string" ||
@@ -173,6 +189,43 @@ function validateChannelManifest(value, channel) {
     }
     return value;
 }
+function validateVersionIndex(value) {
+    if (!isRecord(value) || value.schemaVersion !== "aiwg.resource-version-index/v1") {
+        throw new Error("resource version index has an unsupported schemaVersion");
+    }
+    if (!Array.isArray(value.versions) || value.versions.length > MAX_VERSION_INDEX_ENTRIES) {
+        throw new Error("resource version index has an invalid versions list");
+    }
+    const seenVersions = new Set();
+    const seenDigests = new Set();
+    const versions = [];
+    for (const entry of value.versions) {
+        if (!isRecord(entry) || typeof entry.version !== "string" || !EXACT_VERSION_PATTERN.test(entry.version)) {
+            throw new Error("resource version index contains an invalid version");
+        }
+        const expectedPath = `/resources/${entry.version}/manifest.json`;
+        if (entry.releaseManifest !== expectedPath) {
+            throw new Error(`resource version index entry ${entry.version} has an invalid release manifest path`);
+        }
+        if (typeof entry.releaseManifestSha256 !== "string" || !SHA256_PATTERN.test(entry.releaseManifestSha256)) {
+            throw new Error(`resource version index entry ${entry.version} has an invalid release manifest digest`);
+        }
+        if (seenVersions.has(entry.version))
+            throw new Error(`resource version index contains duplicate version ${entry.version}`);
+        if (seenDigests.has(entry.releaseManifestSha256)) {
+            throw new Error(`resource version index contains duplicate digest ${entry.releaseManifestSha256}`);
+        }
+        seenVersions.add(entry.version);
+        seenDigests.add(entry.releaseManifestSha256);
+        versions.push({
+            version: entry.version,
+            releaseManifest: entry.releaseManifest,
+            releaseManifestSha256: entry.releaseManifestSha256,
+        });
+    }
+    versions.sort((left, right) => semver.rcompare(left.version, right.version));
+    return { schemaVersion: "aiwg.resource-version-index/v1", versions };
+}
 function validateFortemiFiles(manifestBytes, exportBytes) {
     const manifest = parseJson(manifestBytes, "Fortemi Core manifest");
     if (!isRecord(manifest) || manifest.schema_version !== "aiwg.fortemi.prebuilt.v1") {
@@ -487,6 +540,16 @@ function verifyCachedGeneration(cacheRoot, version, digest, selector, publicKeyP
         descriptors,
     };
 }
+function cachedReleaseVersions(cacheRoot) {
+    const root = path.join(cacheRoot, "releases");
+    if (!fs.existsSync(root))
+        return [];
+    assertCacheDirectory(root, "cached releases directory");
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && EXACT_VERSION_PATTERN.test(entry.name))
+        .map((entry) => entry.name)
+        .sort((left, right) => semver.rcompare(left, right));
+}
 function cachedDigests(cacheRoot, version) {
     const root = path.join(cacheRoot, "releases", version);
     if (!fs.existsSync(root))
@@ -576,6 +639,90 @@ function readCachedChannel(cacheRoot, channel, publicKeyPem) {
         throw new Error(`cached channel ${channel} is corrupt and cannot be used offline`);
     return null;
 }
+function versionIndexCacheDir(cacheRoot) {
+    return path.join(cacheRoot, "versions");
+}
+function readCachedVersionIndex(cacheRoot, publicKeyPem) {
+    const dir = versionIndexCacheDir(cacheRoot);
+    if (!fs.existsSync(dir))
+        return null;
+    assertCacheDirectory(dir, "cached resource version index directory");
+    const bytes = readVerifiedRegularFile(path.join(dir, "versions.json"), {
+        label: "cached resource version index",
+        maxBytes: MAX_VERSION_INDEX_BYTES,
+    });
+    const signatureBytes = readVerifiedRegularFile(path.join(dir, "versions.sig"), {
+        label: "cached resource version index signature",
+        maxBytes: MAX_SIGNATURE_BYTES,
+    });
+    verifySignedResourceBytes(bytes, signatureBytes, publicKeyPem, "cached resource version index");
+    return validateVersionIndex(parseJson(bytes, "cached resource version index"));
+}
+function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
+    const target = versionIndexCacheDir(cacheRoot);
+    const stagingRoot = path.join(cacheRoot, ".staging", "versions");
+    fs.mkdirSync(stagingRoot, { recursive: true });
+    const stage = fs.mkdtempSync(path.join(stagingRoot, "index-"));
+    try {
+        fs.writeFileSync(path.join(stage, "versions.json"), bytes, { flag: "wx" });
+        fs.writeFileSync(path.join(stage, "versions.sig"), signatureBytes, { flag: "wx" });
+        if (fs.existsSync(target))
+            fs.rmSync(target, { recursive: true, force: true });
+        installGeneration(stage, target);
+    }
+    catch (error) {
+        fs.rmSync(stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem) {
+    const indexBytes = await fetchBytes(fetcher, resourceUrl(base, "resources/versions.json"), "resource version index", MAX_VERSION_INDEX_BYTES);
+    const signatureBytes = await fetchBytes(fetcher, resourceUrl(base, "resources/versions.sig"), "resource version index signature", MAX_SIGNATURE_BYTES);
+    verifySignedResourceBytes(indexBytes, signatureBytes, publicKeyPem, "resource version index");
+    const index = validateVersionIndex(parseJson(indexBytes, "resource version index"));
+    cacheVersionIndex(cacheRoot, indexBytes, signatureBytes);
+    return index;
+}
+async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offline) {
+    if (offline) {
+        const cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
+        if (cached)
+            return cached;
+        const versions = cachedReleaseVersions(cacheRoot).flatMap((version) => cachedDigests(cacheRoot, version).map((digest) => ({
+            version,
+            releaseManifest: `/resources/${version}/manifest.json`,
+            releaseManifestSha256: digest,
+        })));
+        if (versions.length > 0)
+            return validateVersionIndex({ schemaVersion: "aiwg.resource-version-index/v1", versions });
+        throw new Error("AIWG resource version index is not cached; offline mode cannot resolve range or digest selectors");
+    }
+    if (!fetcher)
+        throw new Error("No fetch implementation is available for AIWG web resources");
+    try {
+        return await fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem);
+    }
+    catch (error) {
+        const cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
+        if (cached)
+            return cached;
+        throw error;
+    }
+}
+function selectVersionFromIndex(index, selector) {
+    if (selector.kind === "digest") {
+        const found = index.versions.find((entry) => entry.releaseManifestSha256 === selector.digest);
+        if (!found)
+            throw new Error(`AIWG resource manifest digest ${selector.value} is not present in the signed version index`);
+        return found;
+    }
+    if (selector.kind !== "range")
+        throw new Error("version index selection requires a range or digest selector");
+    const found = index.versions.find((entry) => semver.satisfies(entry.version, selector.normalizedRange, { includePrerelease: true }));
+    if (!found)
+        throw new Error(`No AIWG resource release satisfies selector '${selector.value}'`);
+    return found;
+}
 function installGeneration(stageDir, targetDir) {
     fsyncTree(stageDir);
     fs.mkdirSync(path.dirname(targetDir), { recursive: true });
@@ -765,6 +912,17 @@ export async function resolveWebRelease(options = {}) {
             throw new Error("No fetch implementation is available for AIWG web resources");
         return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selector.value, publicKeyPem);
     }
+    if (selector.kind === "range" || selector.kind === "digest") {
+        const fetcher = options.fetcher ?? globalThis.fetch;
+        const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline);
+        const selected = selectVersionFromIndex(index, selector);
+        if (options.offline) {
+            return resolveOfflineExact(cacheRoot, selector, selected.version, publicKeyPem, base, selected.releaseManifestSha256);
+        }
+        if (!fetcher)
+            throw new Error("No fetch implementation is available for AIWG web resources");
+        return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selected.version, publicKeyPem, selected.releaseManifestSha256);
+    }
     if (options.offline) {
         const cached = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
         if (!cached)