@pygmalionjs/pygmalion 0.6.32 → 0.6.34

package/node/preview-artifact-plugin.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import fs from 'node:fs/promises';
 import {
   mergeRoutePreviewArtifactV3,
   selectRoutePreviewArtifactFrames,
@@ -9,6 +10,7 @@ import { createPreviewArtifactStore } from './preview-artifact-store.mjs';
 export const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT =
   '/__pygmalion-route-preview/artifact';
 export const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = '/progress';
+export const PYGMALION_REVISION_CATALOG_SUFFIX = '/catalog';
 export const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE =
   'artifacts/pygmalion-route-previews.json';
 
@@ -21,6 +23,7 @@ const MAX_FRAME_REQUEST_COUNT = 2_048;
 // headers). Those arrive as a JSON body instead; the ceiling keeps a stray
 // client from parking megabytes in memory.
 const MAX_FRAME_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
+const MAX_REVISION_CATALOG_BYTES = 16 * 1024 * 1024;
 /**
  * Where a request sits among captures waiting on the same identity. Smaller
  * runs first. The editor sends a frame the designer selected ahead of a
@@ -159,12 +162,15 @@ function requestedFrames(params) {
   }
   if (!Array.isArray(parsed) || parsed.length > MAX_FRAME_REQUEST_COUNT) return null;
   const wanted = [];
+  const ids = new Set();
   for (const entry of parsed) {
     const item = typeof entry === 'string' ? { id: entry } : entry;
     if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
     const id = item.id;
     if (typeof id !== 'string' || !id.trim() || id !== id.trim()) return null;
     if (id.length > MAX_IDENTITY_LENGTH) return null;
+    if (ids.has(id)) return null;
+    ids.add(id);
     const fingerprint = item.fingerprint;
     if (fingerprint !== undefined) {
       if (typeof fingerprint !== 'string' || !fingerprint.trim()) return null;
@@ -259,6 +265,131 @@ function exactArtifact(artifact, namespace, sourceRevision) {
   );
 }
 
+function generatedFramesMatchRequest(artifact, wanted) {
+  const generatedIds = Object.keys(artifact.frames);
+  if (generatedIds.length !== wanted.length) return false;
+  const requested = new Map(wanted.map((frame) => [frame.id, frame]));
+  for (const id of generatedIds) {
+    const request = requested.get(id);
+    if (!request) return false;
+    if (
+      request.fingerprint != null &&
+      artifact.frames[id].fingerprint !== request.fingerprint
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function publicFrameSelection(selection) {
+  const { sourcePending: _sourcePending, ...publicSelection } = selection;
+  return publicSelection;
+}
+
+function freshFrameIds(selection) {
+  const unavailable = new Set([...selection.missing, ...selection.stale]);
+  return Object.keys(selection.bundle.frames).filter((id) => !unavailable.has(id));
+}
+
+function preserveVerifiedFreshness(selection, verifiedIds) {
+  const verified = new Set(verifiedIds);
+  return {
+    ...selection,
+    stale: selection.stale.filter((id) => !verified.has(id)),
+  };
+}
+
+function revisionCatalogErrors(catalog, namespace, sourceRevision) {
+  const errors = [];
+  if (!catalog || typeof catalog !== 'object' || Array.isArray(catalog)) {
+    return ['catalog must be an object'];
+  }
+  if (catalog.version !== 1) errors.push('catalog version must be 1');
+  if (catalog.namespace !== namespace) {
+    errors.push('catalog namespace does not match the request');
+  }
+  if (catalog.sourceRevision !== sourceRevision) {
+    errors.push('catalog sourceRevision does not match the request');
+  }
+  const screens = catalog.screens;
+  if (!screens || typeof screens !== 'object' || Array.isArray(screens)) {
+    errors.push('catalog screens must be an object');
+    return errors;
+  }
+  if (!Number.isInteger(screens.expectedCount) || screens.expectedCount < 0) {
+    errors.push('catalog screens.expectedCount must be a non-negative integer');
+  }
+  if (!Array.isArray(screens.assets)) {
+    errors.push('catalog screens.assets must be an array');
+  } else if (
+    Number.isInteger(screens.expectedCount) &&
+    screens.assets.length !== screens.expectedCount
+  ) {
+    errors.push('catalog screen asset count does not match expectedCount');
+  }
+  if (!Array.isArray(screens.pages)) {
+    errors.push('catalog screens.pages must be an array');
+    return errors;
+  }
+  const pageIds = new Set();
+  for (const page of screens.pages) {
+    const id = page?.importPageId;
+    if (
+      !page ||
+      typeof page !== 'object' ||
+      Array.isArray(page) ||
+      typeof id !== 'string' ||
+      !id.trim() ||
+      id !== id.trim() ||
+      page.importKind !== 'screens' ||
+      typeof page.route !== 'string' ||
+      !page.route.trim()
+    ) {
+      errors.push('catalog contains an invalid screen page');
+      continue;
+    }
+    if (pageIds.has(id)) errors.push(`catalog screen page "${id}" is duplicated`);
+    pageIds.add(id);
+  }
+  for (const asset of Array.isArray(screens.assets) ? screens.assets : []) {
+    if (
+      !asset ||
+      typeof asset !== 'object' ||
+      Array.isArray(asset) ||
+      typeof asset.id !== 'string' ||
+      !asset.id.trim() ||
+      typeof asset.pageId !== 'string' ||
+      !pageIds.has(asset.pageId)
+    ) {
+      errors.push('catalog contains an invalid screen asset');
+    }
+  }
+  return errors;
+}
+
+async function resolveCatalogFile(sourceRoot, catalogFile) {
+  const resolvedSourceRoot = path.resolve(sourceRoot);
+  const resolved = path.resolve(resolvedSourceRoot, catalogFile);
+  if (
+    resolved !== resolvedSourceRoot &&
+    !resolved.startsWith(`${resolvedSourceRoot}${path.sep}`)
+  ) {
+    throw new Error('Revision catalog file must stay inside the source root.');
+  }
+  const [realSourceRoot, realFile] = await Promise.all([
+    fs.realpath(resolvedSourceRoot),
+    fs.realpath(resolved),
+  ]);
+  if (
+    realFile !== realSourceRoot &&
+    !realFile.startsWith(`${realSourceRoot}${path.sep}`)
+  ) {
+    throw new Error('Revision catalog file must stay inside the source root.');
+  }
+  return realFile;
+}
+
 /**
  * Serves an exact local preview artifact identity to the editor runtime.
  * Artifact validation, local-only access, and path containment are enforced by
@@ -267,12 +398,14 @@ function exactArtifact(artifact, namespace, sourceRevision) {
  */
 export function pygmalionPreviewArtifactPlugin({
   root = process.cwd(),
-  sourceRoot,
   artifactFile = DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   endpoint = PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
+  catalogFile,
+  catalogEndpoint = `${endpoint}${PYGMALION_REVISION_CATALOG_SUFFIX}`,
   disabled = () => false,
   generateArtifact,
   acquireLease,
+  acquireSourceLease,
   requestRuntime,
   runtimePrepared = () => true,
   artifactStoreMaxBytes,
@@ -293,6 +426,32 @@ export function pygmalionPreviewArtifactPlugin({
   ) {
     throw new Error('Preview artifact endpoint must be an absolute URL path.');
   }
+  const progressEndpoint = captureProgressEndpoint(endpoint);
+  if (
+    catalogFile != null &&
+    (typeof catalogFile !== 'string' ||
+      !catalogFile.trim() ||
+      path.isAbsolute(catalogFile) ||
+      path.normalize(catalogFile).split(path.sep).includes('..'))
+  ) {
+    throw new Error('Revision catalog file must be a relative path.');
+  }
+  if (
+    typeof catalogEndpoint !== 'string' ||
+    !catalogEndpoint.startsWith('/') ||
+    catalogEndpoint.includes('?') ||
+    catalogEndpoint.includes('#')
+  ) {
+    throw new Error('Revision catalog endpoint must be an absolute URL path.');
+  }
+  if (
+    catalogFile != null &&
+    (catalogEndpoint === endpoint || catalogEndpoint === progressEndpoint)
+  ) {
+    throw new Error(
+      'Revision catalog endpoint must differ from preview artifact endpoints.',
+    );
+  }
   if (typeof disabled !== 'function') {
     throw new TypeError('Preview artifact disabled option must be a function.');
   }
@@ -306,18 +465,26 @@ export function pygmalionPreviewArtifactPlugin({
       'Preview artifact runtime request option must be a function.',
     );
   }
+  if (
+    acquireSourceLease != null &&
+    typeof acquireSourceLease !== 'function'
+  ) {
+    throw new TypeError(
+      'Revision catalog source lease option must be a function.',
+    );
+  }
+  if (catalogFile != null && typeof acquireSourceLease !== 'function') {
+    throw new TypeError(
+      'Revision catalog file requires an exact source lease provider.',
+    );
+  }
   if (typeof runtimePrepared !== 'function') {
     throw new TypeError(
       'Preview artifact runtime readiness option must be a function.',
     );
   }
-  const progressEndpoint = captureProgressEndpoint(endpoint);
-
   const artifactStore = createPreviewArtifactStore({
     artifactFile: resolvedArtifact,
-    // With the source root, a published frame records the files it actually
-    // rendered, so freshness stops depending on which revision captured it.
-    sourceRoot: sourceRoot ?? resolvedRoot,
     ...(artifactStoreMaxBytes == null
       ? {}
       : { maxBytes: artifactStoreMaxBytes }),
@@ -534,6 +701,51 @@ export function pygmalionPreviewArtifactPlugin({
     });
   }
 
+  function answerCatalogPreparing(response) {
+    requestRuntime?.();
+    sendJson(response, 503, {
+      ok: false,
+      error: 'revision_catalog_unavailable',
+      retryable: true,
+      preparing: true,
+      details: ['The source checkout is being prepared.'],
+    });
+  }
+
+  async function readExactRevisionCatalog(namespace, sourceRevision) {
+    const lease = await acquireSourceLease(
+      sourceRevision,
+      `revision-catalog ${sourceRevision.slice(0, 8)}`,
+    );
+    if (!lease) return null;
+    try {
+      if (
+        lease.sourceRevision !== sourceRevision ||
+        typeof lease.sourceRoot !== 'string' ||
+        !lease.sourceRoot.trim()
+      ) {
+        return null;
+      }
+      const file = await resolveCatalogFile(lease.sourceRoot, catalogFile);
+      const stat = await fs.stat(file);
+      if (!stat.isFile() || stat.size > MAX_REVISION_CATALOG_BYTES) {
+        throw new Error('Revision catalog file is missing or too large.');
+      }
+      const catalog = JSON.parse(await fs.readFile(file, 'utf8'));
+      const errors = revisionCatalogErrors(catalog, namespace, sourceRevision);
+      if (errors.length > 0) {
+        throw Object.assign(
+          new Error(`Invalid revision catalog: ${errors.join(', ')}`),
+          { pygmalionBadRevisionCatalog: true },
+        );
+      }
+      await validateSourceLease(lease, sourceRevision);
+      return catalog;
+    } finally {
+      await lease.release();
+    }
+  }
+
   /**
    * A generator that ran and produced the wrong thing.
    *
@@ -548,17 +760,107 @@ export function pygmalionPreviewArtifactPlugin({
     return Object.assign(new Error(message), { pygmalionBadGeneratorOutput: true });
   }
 
+  async function validateSourceLease(lease, sourceRevision) {
+    if (typeof lease?.validate !== 'function') return;
+    let current = false;
+    try {
+      current = (await lease.validate()) === true;
+    } catch {
+      current = false;
+    }
+    if (current) return;
+    throw Object.assign(
+      new Error(
+        `The source checkout for ${sourceRevision.slice(0, 8)} changed while it was being read.`,
+      ),
+      { pygmalionSourceLeaseUnavailable: true },
+    );
+  }
+
+  function sourceContextFromLease(lease, sourceRevision) {
+    if (
+      lease?.sourceRevision !== sourceRevision ||
+      typeof lease?.sourceRoot !== 'string' ||
+      !lease.sourceRoot.trim()
+    ) {
+      return undefined;
+    }
+    return { sourceRevision, sourceRoot: lease.sourceRoot };
+  }
+
+  function retentionSourceContextFromLease(lease, sourceRevision) {
+    return lease?.sourceRootStable === true
+      ? sourceContextFromLease(lease, sourceRevision)
+      : undefined;
+  }
+
+  /**
+   * Refines a conservative cache decision only while the requested checkout is
+   * pinned. Fingerprint hits, recipe mismatches, and frames without observed
+   * dependencies never enter this path; only source-verifiable candidates pay
+   * for the short source lease.
+   */
+  async function withOptionalSourceLease(sourceRevision, label, task) {
+    if (typeof acquireSourceLease !== 'function') return task(undefined);
+    let lease;
+    try {
+      lease = await acquireSourceLease(sourceRevision, label);
+    } catch {
+      return task(undefined);
+    }
+    const sourceContext = sourceContextFromLease(lease, sourceRevision);
+    if (!sourceContext || typeof lease?.release !== 'function') {
+      await lease?.release?.();
+      return task(undefined);
+    }
+    let result;
+    let invalidated = false;
+    try {
+      result = await task(sourceContext);
+      try {
+        await validateSourceLease(lease, sourceRevision);
+      } catch (error) {
+        if (!error?.pygmalionSourceLeaseUnavailable) throw error;
+        invalidated = true;
+      }
+    } finally {
+      await lease.release();
+    }
+    return invalidated ? task(undefined) : result;
+  }
+
   async function withCaptureLease(sourceRevision, task) {
     // A capture reads the dev mirror for minutes. Hold a lease for that whole
     // window so a sync on another server cannot switch the checkout the frames
     // are being rendered from — the artifact would carry this revision's name
     // and another revision's screens.
-    const lease =
-      typeof acquireLease === 'function'
-        ? await acquireLease(`preview-artifact ${sourceRevision.slice(0, 8)}`)
-        : null;
+    const label = `preview-artifact ${sourceRevision.slice(0, 8)}`;
+    let lease;
+    if (typeof acquireSourceLease === 'function') {
+      lease = await acquireSourceLease(sourceRevision, label);
+      if (
+        !lease ||
+        lease.sourceRevision !== sourceRevision ||
+        typeof lease.sourceRoot !== 'string' ||
+        !lease.sourceRoot.trim() ||
+        typeof lease.release !== 'function'
+      ) {
+        await lease?.release?.();
+        requestRuntime?.();
+        throw new Error(
+          `The exact source checkout for ${sourceRevision.slice(0, 8)} is unavailable.`,
+        );
+      }
+    } else {
+      // Compatibility for standalone plugin users that do not compose with a
+      // mirror. createPygmalionVitePlugins always supplies the exact provider.
+      lease =
+        typeof acquireLease === 'function'
+          ? await acquireLease(label)
+          : null;
+    }
     try {
-      return await task();
+      return await task(lease);
     } finally {
       await lease?.release();
     }
@@ -575,29 +877,48 @@ export function pygmalionPreviewArtifactPlugin({
         if (existing) return existing;
         const progress = startCaptureProgress();
         try {
-          const generated = await withCaptureLease(sourceRevision, () =>
-            generateArtifact(
+          const generated = await withCaptureLease(sourceRevision, async (lease) => {
+            const sourceContext = sourceContextFromLease(lease, sourceRevision);
+            const retentionSourceContext = retentionSourceContextFromLease(
+              lease,
+              sourceRevision,
+            );
+            const captured = await generateArtifact(
               {
                 namespace,
                 sourceRevision,
                 ...(captureBaseUrl ? { captureBaseUrl } : {}),
               },
               { onProgress: progress.update },
-            ),
-          );
-          const validation = validateRoutePreviewArtifactBundle(generated);
-          if (!validation.valid) {
-            throw badGeneratorOutput('Generated preview artifact is invalid.');
-          }
-          if (!exactArtifact(generated, namespace, sourceRevision)) {
-            throw badGeneratorOutput(
-              'Generated preview artifact identity does not match the request.',
             );
-          }
-          progress.finalizing();
-          await artifactStore.publishArtifact(generated, {
-            sourceRevision,
-            recordRevision: true,
+            const validation = validateRoutePreviewArtifactBundle(captured);
+            if (!validation.valid) {
+              throw badGeneratorOutput('Generated preview artifact is invalid.');
+            }
+            if (!exactArtifact(captured, namespace, sourceRevision)) {
+              throw badGeneratorOutput(
+                'Generated preview artifact identity does not match the request.',
+              );
+            }
+            const observedDependenciesByFrame = sourceContext
+              ? await artifactStore.observeArtifactDependencies(
+                  captured,
+                  sourceContext.sourceRoot,
+                )
+              : undefined;
+            await validateSourceLease(lease, sourceRevision);
+            progress.finalizing();
+            await artifactStore.publishArtifact(captured, {
+              sourceRevision,
+              recordRevision: true,
+              ...(retentionSourceContext
+                ? { sourceContext: retentionSourceContext }
+                : {}),
+              ...(observedDependenciesByFrame
+                ? { observedDependenciesByFrame }
+                : {}),
+            });
+            return captured;
           });
           return generated;
         } finally {
@@ -621,19 +942,36 @@ export function pygmalionPreviewArtifactPlugin({
     return deduplicateRequest(request, () =>
       enqueueIdentity(namespace, sourceRevision, async () => {
         // A prior request may have filled some frames while this request waited.
-        // Recheck under the namespace/source queue and capture only what remains.
-        const before = await artifactStore.readFrameSelection(
+        // Fingerprint hits remain lock-free. A stale candidate is rechecked under
+        // the capture lease before any generation work starts.
+        const quick = await artifactStore.readFrameSelection(
           namespace,
           sourceRevision,
           wanted,
         );
-        const absent = new Set([...before.missing, ...before.stale]);
-        const remaining = wanted.filter((frame) => absent.has(frame.id));
-        if (remaining.length === 0) return before;
-        const progress = startCaptureProgress(remaining.length);
+        const quickAbsent = new Set([...quick.missing, ...quick.stale]);
+        if (quickAbsent.size === 0) return quick;
+        const progress = startCaptureProgress(quickAbsent.size);
         try {
-          const generated = await withCaptureLease(sourceRevision, () =>
-            generateArtifact(
+          return await withCaptureLease(sourceRevision, async (lease) => {
+            const sourceContext = sourceContextFromLease(lease, sourceRevision);
+            const retentionSourceContext = retentionSourceContextFromLease(
+              lease,
+              sourceRevision,
+            );
+            const before = await artifactStore.readFrameSelection(
+              namespace,
+              sourceRevision,
+              wanted,
+              { sourceContext },
+            );
+            const absent = new Set([...before.missing, ...before.stale]);
+            const remaining = wanted.filter((frame) => absent.has(frame.id));
+            if (remaining.length === 0) {
+              await validateSourceLease(lease, sourceRevision);
+              return before;
+            }
+            const captured = await generateArtifact(
               {
                 namespace,
                 sourceRevision,
@@ -641,33 +979,54 @@ export function pygmalionPreviewArtifactPlugin({
                 ...(captureBaseUrl ? { captureBaseUrl } : {}),
               },
               { onProgress: progress.update },
-            ),
-          );
-          const validation = validateRoutePreviewArtifactBundle(generated);
-          if (!validation.valid || generated.version !== 3) {
-            throw new Error('Generated preview artifact is invalid.');
-          }
-          if (!exactArtifact(generated, namespace, sourceRevision)) {
-            throw new Error(
-              'Generated preview artifact identity does not match the request.',
             );
-          }
-          progress.finalizing();
-          await artifactStore.publishArtifact(generated, {
-            sourceRevision,
-            recordRevision: false,
-            frameRequests: remaining,
-          });
-          // Retention is allowed to decline a newly generated object when older
-          // entries have earned higher read recency. That cache decision must not
-          // discard the result from the request that just paid to generate it.
-          const responseArtifact = mergeRoutePreviewArtifactV3(
-            before.bundle,
-            generated,
-          );
-          return selectRoutePreviewArtifactFrames(responseArtifact, wanted, {
-            includeStale: true,
-            sourceRevision,
+            const validation = validateRoutePreviewArtifactBundle(captured);
+            if (!validation.valid || captured.version !== 3) {
+              throw badGeneratorOutput('Generated preview artifact is invalid.');
+            }
+            if (!exactArtifact(captured, namespace, sourceRevision)) {
+              throw badGeneratorOutput(
+                'Generated preview artifact identity does not match the request.',
+              );
+            }
+            if (!generatedFramesMatchRequest(captured, remaining)) {
+              throw badGeneratorOutput(
+                'Generated preview artifact frames do not match the request.',
+              );
+            }
+            const observedDependenciesByFrame = sourceContext
+              ? await artifactStore.observeArtifactDependencies(
+                  captured,
+                  sourceContext.sourceRoot,
+                )
+              : undefined;
+            await validateSourceLease(lease, sourceRevision);
+            progress.finalizing();
+            await artifactStore.publishArtifact(captured, {
+              sourceRevision,
+              recordRevision: false,
+              frameRequests: remaining,
+              ...(retentionSourceContext
+                ? { sourceContext: retentionSourceContext }
+                : {}),
+              ...(observedDependenciesByFrame
+                ? { observedDependenciesByFrame }
+                : {}),
+            });
+            // Retention is allowed to decline a newly generated object when older
+            // entries have earned higher read recency. That cache decision must not
+            // discard the result from the request that just paid to generate it.
+            const responseArtifact = mergeRoutePreviewArtifactV3(
+              before.bundle,
+              captured,
+            );
+            return preserveVerifiedFreshness(
+              selectRoutePreviewArtifactFrames(responseArtifact, wanted, {
+                includeStale: true,
+                sourceRevision,
+              }),
+              freshFrameIds(before),
+            );
           });
         } finally {
           progress.finish();
@@ -687,6 +1046,71 @@ export function pygmalionPreviewArtifactPlugin({
       void artifactStore.applyRetention?.(undefined)?.catch?.(() => undefined);
       server.middlewares.use(async (request, response, next) => {
         const url = new URL(request.url ?? '/', 'http://localhost');
+        if (catalogFile != null && url.pathname === catalogEndpoint) {
+          if (request.method !== 'GET') {
+            response.setHeader('allow', 'GET');
+            sendJson(response, 405, {
+              ok: false,
+              error: 'method_not_allowed',
+            });
+            return;
+          }
+          if (!isLocalRequestHost(request.headers.host)) {
+            sendJson(response, 403, {
+              ok: false,
+              error: 'local_host_required',
+            });
+            return;
+          }
+          const params = paramsFromQuery(url);
+          const namespace = requestedIdentity(params, 'namespace');
+          const sourceRevision = requestedIdentity(params, 'sourceRevision');
+          if (!namespace || !sourceRevision) {
+            sendJson(response, 400, {
+              ok: false,
+              error: 'invalid_identity',
+            });
+            return;
+          }
+          if (!runtimePrepared()) {
+            answerCatalogPreparing(response);
+            return;
+          }
+          try {
+            const catalog = await readExactRevisionCatalog(
+              namespace,
+              sourceRevision,
+            );
+            if (!catalog) {
+              // Readiness can change after the optimistic check above. A sync
+              // announces that transition before it waits for readers, so a
+              // lease miss during that window is temporary rather than an
+              // identity mismatch the client should cache as permanent.
+              if (!runtimePrepared()) {
+                answerCatalogPreparing(response);
+                return;
+              }
+              sendJson(response, 409, {
+                ok: false,
+                error: 'revision_catalog_identity_mismatch',
+              });
+              return;
+            }
+            sendJson(response, 200, { ok: true, catalog });
+          } catch (error) {
+            if (error?.pygmalionSourceLeaseUnavailable) {
+              answerCatalogPreparing(response);
+              return;
+            }
+            sendJson(response, 500, {
+              ok: false,
+              error: error?.pygmalionBadRevisionCatalog
+                ? 'revision_catalog_invalid'
+                : 'revision_catalog_read_failed',
+            });
+          }
+          return;
+        }
         if (url.pathname === progressEndpoint) {
           if (request.method !== 'GET') {
             response.setHeader('allow', 'GET');
@@ -790,7 +1214,7 @@ export function pygmalionPreviewArtifactPlugin({
         }
         if (wanted !== undefined) {
           if (resolutionOnly(params)) {
-            const resolution = await artifactStore.resolveFrameSelection(
+            const quickResolution = await artifactStore.resolveFrameSelection(
               namespace,
               sourceRevision,
               wanted,
@@ -800,21 +1224,52 @@ export function pygmalionPreviewArtifactPlugin({
             // policy decides by. A cache nobody can inspect is a cache nobody
             // trusts, and "valid vs provenance-only" explains both the size and
             // the next eviction.
-            const store = await artifactStore
-              .inspect(namespace)
-              .catch(() => null);
+            const resolution = quickResolution.sourcePending?.length
+              ? await withOptionalSourceLease(
+                  sourceRevision,
+                  `preview-freshness ${sourceRevision.slice(0, 8)}`,
+                  async (sourceContext) =>
+                    sourceContext
+                      ? await artifactStore.resolveFrameSelection(
+                          namespace,
+                          sourceRevision,
+                          wanted,
+                          { sourceContext },
+                        )
+                      : quickResolution,
+                )
+              : quickResolution;
+            // Inspection is deliberately context-free on this hot path. It
+            // reports observed entries as unknown without re-hashing the whole
+            // cache while a one-frame resolution lease is held.
+            const store = await artifactStore.inspect(namespace).catch(() => null);
             sendJson(response, 200, {
               ok: true,
-              ...resolution,
+              ...publicFrameSelection(resolution),
               ...(store ? { store } : {}),
             });
             return;
           }
-          let picked = await artifactStore.readFrameSelection(
+          const quickPicked = await artifactStore.readFrameSelection(
             namespace,
             sourceRevision,
             wanted,
           );
+          let picked = quickPicked.sourcePending?.length
+            ? await withOptionalSourceLease(
+                sourceRevision,
+                `preview-freshness ${sourceRevision.slice(0, 8)}`,
+                (sourceContext) =>
+                  sourceContext
+                    ? artifactStore.readFrameSelection(
+                        namespace,
+                        sourceRevision,
+                        wanted,
+                        { sourceContext },
+                      )
+                    : quickPicked,
+              )
+            : quickPicked;
           const absent = [...picked.missing, ...picked.stale];
           if (absent.length && generateArtifact && generationAllowed(params)) {
             if (!runtimePrepared()) {
@@ -830,11 +1285,15 @@ export function pygmalionPreviewArtifactPlugin({
                 wanted.filter((frame) => requested.has(frame.id)),
                 priority,
               );
-              picked = selectRoutePreviewArtifactFrames(
+              const merged = selectRoutePreviewArtifactFrames(
                 mergeRoutePreviewArtifactV3(picked.bundle, captured.bundle),
                 wanted,
                 { includeStale: true, sourceRevision },
               );
+              picked = preserveVerifiedFreshness(
+                merged,
+                [...freshFrameIds(picked), ...freshFrameIds(captured)],
+              );
             } catch (error) {
               sendGenerationFailure(response, error);
               return;