veryfront 0.1.764 → 0.1.765

package/esm/src/release-assets/constants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Release Asset Manifest — shared constants.
+ *
+ * @module release-assets/constants
+ */
+/** Current manifest body schema version. */
+export declare const RELEASE_ASSET_MANIFEST_SCHEMA_VERSION: 1;
+/** Public asset base path served on the project's own domain (proxy-owned). */
+export declare const RELEASE_ASSET_BASE_PATH: "/_vf/assets";
+/** Content types permitted for release assets. */
+export declare const RELEASE_ASSET_CONTENT_TYPES: {
+    readonly js: "text/javascript";
+    readonly css: "text/css";
+};
+export type ReleaseAssetExtension = keyof typeof RELEASE_ASSET_CONTENT_TYPES;
+export type ReleaseAssetContentType = (typeof RELEASE_ASSET_CONTENT_TYPES)[ReleaseAssetExtension];
+/** Allowlist of accepted content types (upstream + upload validation). */
+export declare const RELEASE_ASSET_CONTENT_TYPE_ALLOWLIST: readonly ReleaseAssetContentType[];
+/** Maximum size (bytes) for a single uploaded asset (10 MB). */
+export declare const RELEASE_ASSET_MAX_SIZE_BYTES: number;
+/** Immutable cache max-age in seconds (1 year). */
+export declare const RELEASE_ASSET_IMMUTABLE_MAX_AGE_SECONDS = 31536000;
+/** Bounded upload concurrency when posting assets during a build. */
+export declare const RELEASE_ASSET_UPLOAD_CONCURRENCY = 8;
+/** Env flag that enables HTML manifest consumption in production (default OFF). */
+export declare const RELEASE_ASSET_MANIFEST_ENV_FLAG = "VERYFRONT_RELEASE_ASSET_MANIFEST";
+/** Map a 64-hex content hash + extension to its public asset URL. */
+export declare function releaseAssetUrl(contentHash: string, extension: ReleaseAssetExtension): string;
+/** Resolve the content type for an extension, or null if not allowed. */
+export declare function contentTypeForExtension(extension: string): ReleaseAssetContentType | null;
+/** True when the value is a valid allowlisted release asset content type. */
+export declare function isAllowedReleaseAssetContentType(value: string | null | undefined): value is ReleaseAssetContentType;
+/** Validate a content hash is exactly 64 lowercase hex characters. */
+export declare function isValidContentHash(hash: string): boolean;
+//# sourceMappingURL=constants.d.ts.map

package/esm/src/release-assets/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/src/release-assets/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,qCAAqC,EAAG,CAAU,CAAC;AAEhE,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,EAAG,aAAsB,CAAC;AAE9D,kDAAkD;AAClD,eAAO,MAAM,2BAA2B;;;CAG9B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,2BAA2B,CAAC;AAC7E,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,qBAAqB,CAAC,CAAC;AAElG,0EAA0E;AAC1E,eAAO,MAAM,oCAAoC,EAAE,SAAS,uBAAuB,EAGlF,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D,mDAAmD;AACnD,eAAO,MAAM,uCAAuC,WAAa,CAAC;AAElE,qEAAqE;AACrE,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,mFAAmF;AACnF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAElF,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,GAAG,MAAM,CAE7F;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB,uBAAuB,GAAG,IAAI,CAIhC;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,KAAK,IAAI,uBAAuB,CAIlC;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/esm/src/release-assets/constants.js

@@ -0,0 +1,50 @@
+/**
+ * Release Asset Manifest — shared constants.
+ *
+ * @module release-assets/constants
+ */
+/** Current manifest body schema version. */
+export const RELEASE_ASSET_MANIFEST_SCHEMA_VERSION = 1;
+/** Public asset base path served on the project's own domain (proxy-owned). */
+export const RELEASE_ASSET_BASE_PATH = "/_vf/assets";
+/** Content types permitted for release assets. */
+export const RELEASE_ASSET_CONTENT_TYPES = {
+    js: "text/javascript",
+    css: "text/css",
+};
+/** Allowlist of accepted content types (upstream + upload validation). */
+export const RELEASE_ASSET_CONTENT_TYPE_ALLOWLIST = [
+    RELEASE_ASSET_CONTENT_TYPES.js,
+    RELEASE_ASSET_CONTENT_TYPES.css,
+];
+/** Maximum size (bytes) for a single uploaded asset (10 MB). */
+export const RELEASE_ASSET_MAX_SIZE_BYTES = 10 * 1024 * 1024;
+/** Immutable cache max-age in seconds (1 year). */
+export const RELEASE_ASSET_IMMUTABLE_MAX_AGE_SECONDS = 31_536_000;
+/** Bounded upload concurrency when posting assets during a build. */
+export const RELEASE_ASSET_UPLOAD_CONCURRENCY = 8;
+/** Env flag that enables HTML manifest consumption in production (default OFF). */
+export const RELEASE_ASSET_MANIFEST_ENV_FLAG = "VERYFRONT_RELEASE_ASSET_MANIFEST";
+/** Map a 64-hex content hash + extension to its public asset URL. */
+export function releaseAssetUrl(contentHash, extension) {
+    return `${RELEASE_ASSET_BASE_PATH}/${contentHash}.${extension}`;
+}
+/** Resolve the content type for an extension, or null if not allowed. */
+export function contentTypeForExtension(extension) {
+    if (extension === "js")
+        return RELEASE_ASSET_CONTENT_TYPES.js;
+    if (extension === "css")
+        return RELEASE_ASSET_CONTENT_TYPES.css;
+    return null;
+}
+/** True when the value is a valid allowlisted release asset content type. */
+export function isAllowedReleaseAssetContentType(value) {
+    if (!value)
+        return false;
+    const base = value.split(";")[0]?.trim();
+    return RELEASE_ASSET_CONTENT_TYPE_ALLOWLIST.some((allowed) => allowed === base);
+}
+/** Validate a content hash is exactly 64 lowercase hex characters. */
+export function isValidContentHash(hash) {
+    return /^[0-9a-f]{64}$/.test(hash);
+}

package/esm/src/release-assets/hash.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Release Asset Manifest — SHA-256 helper.
+ *
+ * Produces lowercase hex SHA-256 digests of raw asset bytes using the Web
+ * Crypto API (`crypto.subtle`), matching the content-addressing contract.
+ *
+ * @module release-assets/hash
+ */
+import * as dntShim from "../../_dnt.shims.js";
+/** Compute the lowercase hex SHA-256 digest of raw bytes. */
+export declare function sha256HexBytes(bytes: dntShim.BufferSource): Promise<string>;
+/** Compute the lowercase hex SHA-256 digest of a UTF-8 string. */
+export declare function sha256Hex(input: string): Promise<string>;
+//# sourceMappingURL=hash.d.ts.map

package/esm/src/release-assets/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/src/release-assets/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAO/C,6DAA6D;AAC7D,wBAAsB,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAGjF;AAED,kEAAkE;AAClE,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9D"}

package/esm/src/release-assets/hash.js

@@ -0,0 +1,22 @@
+/**
+ * Release Asset Manifest — SHA-256 helper.
+ *
+ * Produces lowercase hex SHA-256 digests of raw asset bytes using the Web
+ * Crypto API (`crypto.subtle`), matching the content-addressing contract.
+ *
+ * @module release-assets/hash
+ */
+import * as dntShim from "../../_dnt.shims.js";
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Compute the lowercase hex SHA-256 digest of raw bytes. */
+export async function sha256HexBytes(bytes) {
+    const digest = await dntShim.crypto.subtle.digest("SHA-256", bytes);
+    return toHex(digest);
+}
+/** Compute the lowercase hex SHA-256 digest of a UTF-8 string. */
+export async function sha256Hex(input) {
+    const digest = await dntShim.crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+    return toHex(digest);
+}

package/esm/src/release-assets/html-consumption.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Release Asset Manifest — HTML consumption helpers.
+ *
+ * Pure helpers used by the HTML shell generator to rewrite module URLs and
+ * preload hints to content-addressed `/_vf/assets/{hash}.js` URLs when a ready
+ * manifest covers the entry. Misses fall back to the existing URL (per-entry)
+ * and are counted via structured debug logs.
+ *
+ * @module release-assets/html-consumption
+ */
+import type { ReleaseAssetManifest } from "./manifest-schema.js";
+/**
+ * Normalize a logical module path to the manifest's key convention.
+ *
+ * The HTML shell works with relative source paths like `pages/index.tsx` and
+ * `/_vf_modules/pages/index.js` URLs. Manifest module keys use the logical
+ * source path (e.g. `pages/index.tsx`). This strips a leading `/_vf_modules/`
+ * and any `.js` URL extension so both forms resolve.
+ */
+export declare function normalizeManifestModuleKey(path: string): string;
+/**
+ * Resolve a module URL through the manifest.
+ *
+ * Returns the content-addressed asset URL on a hit, or null on a miss (caller
+ * keeps the existing URL). The manifest is consulted by both the logical key
+ * and its `.js`-stripped form to tolerate either input shape.
+ */
+export declare function resolveManifestModuleUrl(manifest: ReleaseAssetManifest, logicalPath: string): string | null;
+/** Resolve the route closure module URLs for preload hints from the manifest. */
+export declare function resolveManifestRoutePreloadUrls(manifest: ReleaseAssetManifest, route: string): string[];
+//# sourceMappingURL=html-consumption.d.ts.map

package/esm/src/release-assets/html-consumption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-consumption.d.ts","sourceRoot":"","sources":["../../../src/src/release-assets/html-consumption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAIjE;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAcf;AAED,iFAAiF;AACjF,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,MAAM,GACZ,MAAM,EAAE,CAcV"}

package/esm/src/release-assets/html-consumption.js

@@ -0,0 +1,64 @@
+/**
+ * Release Asset Manifest — HTML consumption helpers.
+ *
+ * Pure helpers used by the HTML shell generator to rewrite module URLs and
+ * preload hints to content-addressed `/_vf/assets/{hash}.js` URLs when a ready
+ * manifest covers the entry. Misses fall back to the existing URL (per-entry)
+ * and are counted via structured debug logs.
+ *
+ * @module release-assets/html-consumption
+ */
+import { serverLogger } from "../utils/index.js";
+import { releaseAssetUrl } from "./constants.js";
+const logger = serverLogger.component("release-asset-consume");
+/**
+ * Normalize a logical module path to the manifest's key convention.
+ *
+ * The HTML shell works with relative source paths like `pages/index.tsx` and
+ * `/_vf_modules/pages/index.js` URLs. Manifest module keys use the logical
+ * source path (e.g. `pages/index.tsx`). This strips a leading `/_vf_modules/`
+ * and any `.js` URL extension so both forms resolve.
+ */
+export function normalizeManifestModuleKey(path) {
+    let key = path.replace(/^\/?_vf_modules\//, "");
+    key = key.replace(/^\/+/, "");
+    return key;
+}
+/**
+ * Resolve a module URL through the manifest.
+ *
+ * Returns the content-addressed asset URL on a hit, or null on a miss (caller
+ * keeps the existing URL). The manifest is consulted by both the logical key
+ * and its `.js`-stripped form to tolerate either input shape.
+ */
+export function resolveManifestModuleUrl(manifest, logicalPath) {
+    const key = normalizeManifestModuleKey(logicalPath);
+    const direct = manifest.modules[key];
+    if (direct)
+        return releaseAssetUrl(direct.contentHash, "js");
+    // Tolerate keys that differ only by extension (e.g. ".js" vs source ext).
+    const withoutExt = key.replace(/\.(tsx|ts|jsx|mdx|js)$/, "");
+    for (const candidateExt of [".tsx", ".ts", ".jsx", ".mdx", ".js"]) {
+        const candidate = manifest.modules[withoutExt + candidateExt];
+        if (candidate)
+            return releaseAssetUrl(candidate.contentHash, "js");
+    }
+    logger.debug("manifest module miss", { key });
+    return null;
+}
+/** Resolve the route closure module URLs for preload hints from the manifest. */
+export function resolveManifestRoutePreloadUrls(manifest, route) {
+    const entry = manifest.routes[route] ?? manifest.routes[`/${route}`] ??
+        manifest.routes[route.replace(/^\//, "")];
+    if (!entry) {
+        logger.debug("manifest route miss", { route });
+        return [];
+    }
+    const urls = [];
+    for (const modulePath of entry.modules) {
+        const asset = manifest.modules[modulePath];
+        if (asset)
+            urls.push(releaseAssetUrl(asset.contentHash, "js"));
+    }
+    return urls;
+}

package/esm/src/release-assets/manifest-cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Release Asset Manifest — in-process consumption cache (production HTML).
+ *
+ * Fetches manifests from the project-scoped GET endpoint once per release and
+ * caches them keyed by `${releaseId}:${manifestVersion}`. Ready manifests are
+ * cached for a bounded TTL (15 min) so superseded manifests are eventually
+ * replaced; non-ready / missing results are cached for a short TTL so the
+ * common "no manifest" case stays cheap.
+ *
+ * Consumption is gated by `VERYFRONT_RELEASE_ASSET_MANIFEST=1` (default OFF).
+ * When the flag is off, `getReadyManifestForRender` always returns null so the
+ * HTML output is byte-identical to today.
+ *
+ * The HTML shell is synchronous, so reads are non-blocking: a cache miss kicks
+ * off a background fetch and returns null for the current render. Subsequent
+ * renders for the same release pick up the cached result.
+ *
+ * Multi-tenancy: each releaseId is served by the fetcher registered for that
+ * specific releaseId (the adapter that owns it). There is no cross-project
+ * token reuse. If no per-releaseId fetcher is registered, the call returns null
+ * (byte-identical JIT fallback).
+ *
+ * @module release-assets/manifest-cache
+ */
+import { type ReleaseAssetManifest } from "./manifest-schema.js";
+/**
+ * Fetcher used to retrieve a manifest for a release. Registered per-releaseId
+ * by the runtime adapter that owns that release, so the correct project-scoped
+ * token is always used. Returns null when the manifest is unavailable.
+ */
+export interface ReleaseAssetManifestFetcher {
+    (releaseId: string): Promise<{
+        state: string;
+        manifest: ReleaseAssetManifest | null;
+    } | null>;
+}
+/**
+ * Register a project-scoped manifest fetcher for the given releaseId.
+ *
+ * Called by the FS adapter when its content context is set to a release.
+ * Overwrites any previous registration for the same releaseId (safe — the
+ * latest adapter for a release is the authoritative owner).
+ */
+export declare function registerManifestFetcherForRelease(releaseId: string, fetcher: ReleaseAssetManifestFetcher): void;
+/**
+ * Remove the manifest fetcher for the given releaseId.
+ *
+ * Called when an adapter transitions away from a release context.
+ */
+export declare function unregisterManifestFetcherForRelease(releaseId: string): void;
+/**
+ * Register a single global fetcher (for tests / simple single-project setups).
+ *
+ * In production multi-tenant mode prefer `registerManifestFetcherForRelease`.
+ * Passing `undefined` clears the global fallback.
+ */
+export declare function configureReleaseAssetManifestFetcher(fetcher: ReleaseAssetManifestFetcher | undefined): void;
+/** True when production manifest consumption is enabled via env flag. */
+export declare function isReleaseAssetManifestEnabled(): boolean;
+/**
+ * Return a ready manifest for `releaseId` if one is cached, else null.
+ *
+ * Non-blocking: on a cache miss (or expired entry) it schedules a background
+ * fetch and returns null for the current render. Returns null immediately when
+ * the flag is off or no fetcher is registered for this releaseId.
+ */
+export declare function getReadyManifestForRender(releaseId: string | null | undefined): ReleaseAssetManifest | null;
+/** Clear the cache (deployment / memory pressure / tests). */
+export declare function clearReleaseAssetManifestCache(): void;
+//# sourceMappingURL=manifest-cache.d.ts.map

package/esm/src/release-assets/manifest-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-cache.d.ts","sourceRoot":"","sources":["../../../src/src/release-assets/manifest-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,EAA6B,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAuB5F;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAC1B;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAChE,CAAC;CACH;AAKD;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,2BAA2B,GAAG,SAAS,GAC/C,IAAI,CAMN;AASD,yEAAyE;AACzE,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAOD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,oBAAoB,GAAG,IAAI,CA+B7B;AA+CD,8DAA8D;AAC9D,wBAAgB,8BAA8B,IAAI,IAAI,CAIrD"}

package/esm/src/release-assets/manifest-cache.js

@@ -0,0 +1,178 @@
+/**
+ * Release Asset Manifest — in-process consumption cache (production HTML).
+ *
+ * Fetches manifests from the project-scoped GET endpoint once per release and
+ * caches them keyed by `${releaseId}:${manifestVersion}`. Ready manifests are
+ * cached for a bounded TTL (15 min) so superseded manifests are eventually
+ * replaced; non-ready / missing results are cached for a short TTL so the
+ * common "no manifest" case stays cheap.
+ *
+ * Consumption is gated by `VERYFRONT_RELEASE_ASSET_MANIFEST=1` (default OFF).
+ * When the flag is off, `getReadyManifestForRender` always returns null so the
+ * HTML output is byte-identical to today.
+ *
+ * The HTML shell is synchronous, so reads are non-blocking: a cache miss kicks
+ * off a background fetch and returns null for the current render. Subsequent
+ * renders for the same release pick up the cached result.
+ *
+ * Multi-tenancy: each releaseId is served by the fetcher registered for that
+ * specific releaseId (the adapter that owns it). There is no cross-project
+ * token reuse. If no per-releaseId fetcher is registered, the call returns null
+ * (byte-identical JIT fallback).
+ *
+ * @module release-assets/manifest-cache
+ */
+import { serverLogger } from "../utils/index.js";
+import { LRUCache } from "../utils/lru-wrapper.js";
+import { registerLRUCache } from "../cache/index.js";
+import { getEnv } from "../platform/compat/process.js";
+import { RELEASE_ASSET_MANIFEST_ENV_FLAG } from "./constants.js";
+import { parseReleaseAssetManifest } from "./manifest-schema.js";
+const logger = serverLogger.component("release-asset-manifest");
+/** Bound on cached manifests (per releaseId:manifestVersion). */
+const MAX_CACHED_MANIFESTS = 500;
+/** Short TTL for non-ready / missing results (ms). */
+const NON_READY_TTL_MS = 30_000;
+/** TTL for ready manifests — long but finite so superseded entries are picked up (15 min). */
+const READY_TTL_MS = 15 * 60 * 1000;
+const manifestCache = new LRUCache({ maxEntries: MAX_CACHED_MANIFESTS });
+registerLRUCache("release-asset-manifest-cache", manifestCache);
+/** In-flight fetches, deduped per releaseId. */
+const inFlight = new Map();
+/** Per-releaseId fetcher registry (keyed by releaseId). */
+const fetcherRegistry = new Map();
+/**
+ * Register a project-scoped manifest fetcher for the given releaseId.
+ *
+ * Called by the FS adapter when its content context is set to a release.
+ * Overwrites any previous registration for the same releaseId (safe — the
+ * latest adapter for a release is the authoritative owner).
+ */
+export function registerManifestFetcherForRelease(releaseId, fetcher) {
+    fetcherRegistry.set(releaseId, fetcher);
+}
+/**
+ * Remove the manifest fetcher for the given releaseId.
+ *
+ * Called when an adapter transitions away from a release context.
+ */
+export function unregisterManifestFetcherForRelease(releaseId) {
+    fetcherRegistry.delete(releaseId);
+}
+/**
+ * Register a single global fetcher (for tests / simple single-project setups).
+ *
+ * In production multi-tenant mode prefer `registerManifestFetcherForRelease`.
+ * Passing `undefined` clears the global fallback.
+ */
+export function configureReleaseAssetManifestFetcher(fetcher) {
+    if (fetcher) {
+        fetcherRegistry.set("*", fetcher);
+    }
+    else {
+        fetcherRegistry.delete("*");
+    }
+}
+/** Resolve the fetcher for a releaseId: prefer per-releaseId, then global fallback. */
+function resolveFetcher(releaseId) {
+    return fetcherRegistry.get(releaseId) ?? fetcherRegistry.get("*");
+}
+/** True when production manifest consumption is enabled via env flag. */
+export function isReleaseAssetManifestEnabled() {
+    return getEnv(RELEASE_ASSET_MANIFEST_ENV_FLAG) === "1";
+}
+/** Build the cache key from releaseId + the latest known manifestVersion. */
+function cacheKey(releaseId, manifestVersion) {
+    return manifestVersion !== undefined ? `${releaseId}:${manifestVersion}` : releaseId;
+}
+/**
+ * Return a ready manifest for `releaseId` if one is cached, else null.
+ *
+ * Non-blocking: on a cache miss (or expired entry) it schedules a background
+ * fetch and returns null for the current render. Returns null immediately when
+ * the flag is off or no fetcher is registered for this releaseId.
+ */
+export function getReadyManifestForRender(releaseId) {
+    if (!releaseId)
+        return null;
+    if (!isReleaseAssetManifestEnabled())
+        return null;
+    if (!resolveFetcher(releaseId))
+        return null;
+    // Look up the most recent cached entry for this release. We do a prefix scan
+    // of the LRU to find any `releaseId:*` entry; if we find a live ready one we
+    // return it without scheduling another fetch.
+    let best = null;
+    for (const [k, v] of manifestCache.entries()) {
+        if (k !== releaseId && !k.startsWith(`${releaseId}:`))
+            continue;
+        if (v.expiresAt > Date.now() && v.manifest) {
+            // Prefer the entry with the highest manifest version.
+            const existingVersion = best?.manifest?.manifestVersion ?? -1;
+            if ((v.manifest.manifestVersion ?? 0) > existingVersion) {
+                best = v;
+            }
+        }
+    }
+    if (best)
+        return best.manifest;
+    // Also check the plain releaseId slot (non-ready / null entry).
+    const plain = manifestCache.get(releaseId);
+    if (plain && plain.expiresAt > Date.now()) {
+        // Non-ready entry still warm — return null without scheduling another fetch.
+        return null;
+    }
+    scheduleFetch(releaseId);
+    return null;
+}
+function scheduleFetch(releaseId) {
+    if (inFlight.has(releaseId))
+        return;
+    const active = resolveFetcher(releaseId);
+    if (!active)
+        return;
+    const promise = (async () => {
+        try {
+            const result = await active(releaseId);
+            if (!result) {
+                manifestCache.set(releaseId, { manifest: null, expiresAt: Date.now() + NON_READY_TTL_MS });
+                return;
+            }
+            const manifest = result.state === "ready" && result.manifest
+                ? parseReleaseAssetManifest(result.manifest)
+                : null;
+            if (manifest) {
+                const key = cacheKey(releaseId, manifest.manifestVersion);
+                manifestCache.set(key, { manifest, expiresAt: Date.now() + READY_TTL_MS });
+                logger.debug("Cached ready manifest", {
+                    releaseId,
+                    manifestVersion: manifest.manifestVersion,
+                    ttlMs: READY_TTL_MS,
+                });
+            }
+            else {
+                manifestCache.set(releaseId, {
+                    manifest: null,
+                    expiresAt: Date.now() + NON_READY_TTL_MS,
+                });
+            }
+        }
+        catch (error) {
+            logger.debug("Manifest fetch failed", {
+                releaseId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            manifestCache.set(releaseId, { manifest: null, expiresAt: Date.now() + NON_READY_TTL_MS });
+        }
+        finally {
+            inFlight.delete(releaseId);
+        }
+    })();
+    inFlight.set(releaseId, promise);
+}
+/** Clear the cache (deployment / memory pressure / tests). */
+export function clearReleaseAssetManifestCache() {
+    manifestCache.clear();
+    inFlight.clear();
+    fetcherRegistry.clear();
+}

package/esm/src/release-assets/manifest-schema.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Release Asset Manifest — v1 body schema, types, and validator.
+ *
+ * The manifest body is content-addressed metadata describing the transformed
+ * browser modules and compiled CSS for a release, plus the per-route closure
+ * used to drive preload hints and asset URL rewriting.
+ *
+ * Validation follows the repo's `defineSchema` convention (zod via the
+ * `SchemaValidator` extension contract). The schema is materialized lazily so
+ * core modules can import these types without pulling in the validator.
+ *
+ * @module release-assets/manifest-schema
+ */
+import type { InferSchema } from "../extensions/schema/index.js";
+export declare const getReleaseAssetManifestSchema: () => import("../internal-agents/schema.js").Schema<import("../extensions/schema/schema-validator.js").InferShape<{
+    schemaVersion: import("../internal-agents/schema.js").Schema<1>;
+    projectId: import("../internal-agents/schema.js").Schema<string>;
+    releaseId: import("../internal-agents/schema.js").Schema<string>;
+    releaseVersion: import("../internal-agents/schema.js").Schema<number>;
+    manifestVersion: import("../internal-agents/schema.js").Schema<number>;
+    builderVersion: import("../internal-agents/schema.js").Schema<string>;
+    sourceContentHash: import("../internal-agents/schema.js").Schema<string>;
+    createdAt: import("../internal-agents/schema.js").Schema<string>;
+    assetBasePath: import("../internal-agents/schema.js").Schema<string>;
+    modules: import("../internal-agents/schema.js").Schema<Record<string, import("../extensions/schema/schema-validator.js").InferShape<{
+        contentHash: import("../internal-agents/schema.js").Schema<string>;
+        size: import("../internal-agents/schema.js").Schema<number>;
+        contentType: import("../internal-agents/schema.js").Schema<string>;
+    }>>>;
+    css: import("../internal-agents/schema.js").Schema<import("../extensions/schema/schema-validator.js").InferShape<{
+        contentHash: import("../internal-agents/schema.js").Schema<string>;
+        size: import("../internal-agents/schema.js").Schema<number>;
+        contentType: import("../internal-agents/schema.js").Schema<string>;
+        styleProfileHash: import("../internal-agents/schema.js").Schema<string | null>;
+    }>[]>;
+    routes: import("../internal-agents/schema.js").Schema<Record<string, import("../extensions/schema/schema-validator.js").InferShape<{
+        modules: import("../internal-agents/schema.js").Schema<string[]>;
+        css: import("../internal-agents/schema.js").Schema<string[]>;
+    }>>>;
+    dependencies: import("../internal-agents/schema.js").Schema<Record<string, import("../extensions/schema/schema-validator.js").InferShape<{
+        contentHash: import("../internal-agents/schema.js").Schema<string>;
+        size: import("../internal-agents/schema.js").Schema<number>;
+        contentType: import("../internal-agents/schema.js").Schema<string>;
+    }>>>;
+    fallback: import("../internal-agents/schema.js").Schema<import("../extensions/schema/schema-validator.js").InferShape<{
+        mode: import("../internal-agents/schema.js").Schema<"jit">;
+        gaps: import("../internal-agents/schema.js").Schema<string[]>;
+    }>>;
+}>>;
+export type ReleaseAssetManifest = InferSchema<ReturnType<typeof getReleaseAssetManifestSchema>>;
+export type ReleaseAssetEntry = ReleaseAssetManifest["modules"][string];
+export type ReleaseAssetCssEntry = ReleaseAssetManifest["css"][number];
+export type ReleaseAssetRouteEntry = ReleaseAssetManifest["routes"][string];
+/** Manifest lifecycle states (DB-owned; mirrored here for runtime checks). */
+export type ReleaseAssetManifestState = "queued" | "building" | "partial" | "ready" | "failed" | "superseded";
+/** Response shape for the GET asset-manifest endpoint. */
+export interface ReleaseAssetManifestResponse {
+    state: ReleaseAssetManifestState;
+    manifest_version: number;
+    manifest: ReleaseAssetManifest | null;
+}
+/**
+ * Hand-rolled structural validator.
+ *
+ * Used on consumption paths (HTML/proxy) where the `SchemaValidator` extension
+ * may not be registered. Returns the typed manifest on success, or null. Does
+ * not throw — consumption is always best-effort with a JIT fallback.
+ */
+export declare function parseReleaseAssetManifest(value: unknown): ReleaseAssetManifest | null;
+//# sourceMappingURL=manifest-schema.d.ts.map

package/esm/src/release-assets/manifest-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-schema.d.ts","sourceRoot":"","sources":["../../../src/src/release-assets/manifest-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,+BAA+B,CAAC;AAkClF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmBzC,CAAC;AAMF,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAC5C,UAAU,CAAC,OAAO,6BAA6B,CAAC,CACjD,CAAC;AACF,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AACxE,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,MAAM,MAAM,sBAAsB,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,8EAA8E;AAC9E,MAAM,MAAM,yBAAyB,GACjC,QAAQ,GACR,UAAU,GACV,SAAS,GACT,OAAO,GACP,QAAQ,GACR,YAAY,CAAC;AAEjB,0DAA0D;AAC1D,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,yBAAyB,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAuBrF"}