snapdrift 0.8.1 → 0.8.2

package/lib/snap-provider.mjs

@@ -32,6 +32,10 @@ const RETRY_MULTIPLIER = 2;
 const MAX_RETRY_TOTAL_MS = 30000;
 const POLL_INTERVAL_MS = 2000;
 const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
+const MAX_STABLE_INCOMPLETE_POLLS = 30;
+const BASELINE_RUN_SUCCESS_STATUS = 'new';
+const BASELINE_CAPTURE_SUCCESS_STATUS = 'new';
+const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
 
 // Snap reports a run as "new" when it has no baseline to compare against (first
 // capture for a project, or any baseline-publish run that intentionally omits a
@@ -39,6 +43,180 @@ const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
 // client must stop polling on it just like pass/fail/error.
 const TERMINAL_RUN_STATUSES = new Set(['pass', 'fail', 'error', 'new']);
 
+/** @param {string} detail @returns {Error} */
+function completeBaselineError(detail) {
+  return new Error(`Cannot publish a complete Snap baseline: ${detail}`);
+}
+
+/**
+ * @param {import('../types/visual-diff-types').VisualViewport} viewport
+ * @returns {{ width: number, height: number, deviceScaleFactor?: number, isMobile?: boolean, hasTouch?: boolean }}
+ */
+function resolveViewportDescriptor(viewport) {
+  return typeof viewport === 'string'
+    ? (VIEWPORT_PRESETS[viewport] ?? { width: 1280, height: 720 })
+    : viewport;
+}
+
+/** @param {VisualRegressionConfig['routes'][number]} route */
+function expectedCaptureIdentity(route) {
+  return {
+    routeId: route.id,
+    routePath: route.path,
+    viewportDescriptorJson: JSON.stringify(resolveViewportDescriptor(route.viewport))
+  };
+}
+
+/** @param {unknown} value @param {string} context @returns {string} */
+function normalizeViewportDescriptor(value, context) {
+  let descriptor;
+  try {
+    descriptor = typeof value === 'string' ? JSON.parse(value) : value;
+  } catch {
+    throw completeBaselineError(`${context} has malformed viewportDescriptorJson.`);
+  }
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor) ||
+      !Number.isFinite(descriptor.width) || !Number.isFinite(descriptor.height)) {
+    throw completeBaselineError(`${context} has an invalid viewport descriptor.`);
+  }
+  return JSON.stringify(Object.fromEntries(
+    Object.entries(descriptor).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+  ));
+}
+
+/** @param {{ routeId?: unknown, viewportDescriptorJson?: unknown }} capture @param {string} context */
+function captureIdentityKey(capture, context) {
+  if (typeof capture.routeId !== 'string' || !capture.routeId) {
+    throw completeBaselineError(`${context} has no routeId.`);
+  }
+  return `${capture.routeId}\u0000${normalizeViewportDescriptor(capture.viewportDescriptorJson, context)}`;
+}
+
+/** @param {unknown} value @param {string} field @returns {Set<string>} */
+function uniqueRouteIdSet(value, field) {
+  if (!Array.isArray(value) || value.some((id) => typeof id !== 'string' || !id)) {
+    throw completeBaselineError(`results metadata has no valid ${field}; capture again with SnapDrift 0.8.2 or newer.`);
+  }
+  const ids = new Set(value);
+  if (ids.size !== value.length) {
+    throw completeBaselineError(`results metadata ${field} contains duplicate route ids.`);
+  }
+  return ids;
+}
+
+/** @param {string[]} configuredRouteIds @param {string[]} selectedRouteIds */
+function assertCompleteHostedBaselineSelection(configuredRouteIds, selectedRouteIds) {
+  const selected = new Set(selectedRouteIds);
+  const missing = configuredRouteIds.filter((id) => !selected.has(id));
+  if (missing.length === 0 && selected.size === configuredRouteIds.length) return;
+  throw new Error(
+    `Hosted Snap baseline publication requires all ${configuredRouteIds.length} configured route(s), ` +
+    `but only ${selected.size} were selected. Remove route-ids/--routes scoping ` +
+    `(missing: ${missing.join(', ') || 'unknown'}). Scoped runs remain supported for PR diffs ` +
+    'and local-provider baselines.'
+  );
+}
+
+/**
+ * @param {import('../types/visual-diff-types').SnapRunMetadata} metadata
+ * @param {JsonObject} run
+ * @param {string} projectId
+ */
+function validateCompleteBaselineRun(metadata, run, projectId) {
+  if (metadata.projectId !== projectId) {
+    throw completeBaselineError(`source run belongs to project "${metadata.projectId || 'unknown'}", not "${projectId}".`);
+  }
+  if (metadata.purpose !== 'baseline') {
+    throw completeBaselineError('source results were not recorded as a baseline capture.');
+  }
+  if (typeof metadata.refBranch !== 'string' || !metadata.refBranch ||
+      typeof metadata.refSha !== 'string' || !metadata.refSha) {
+    throw completeBaselineError('source results have no resolved ref; capture again with SnapDrift 0.8.2 or newer.');
+  }
+  if (
+    typeof metadata.publicationSequence !== 'number' ||
+    !Number.isSafeInteger(metadata.publicationSequence) ||
+    metadata.publicationSequence <= 0
+  ) {
+    throw completeBaselineError(
+      'source results have no valid publication sequence; capture again with SnapDrift 0.8.2 or newer.'
+    );
+  }
+  if (typeof metadata.publicationWorkflowRef !== 'string' || !metadata.publicationWorkflowRef.trim()) {
+    throw completeBaselineError(
+      'source results have no publication workflow identity; capture again with SnapDrift 0.8.2 or newer.'
+    );
+  }
+
+  const configured = uniqueRouteIdSet(metadata.configuredRouteIds, 'configuredRouteIds');
+  const selected = uniqueRouteIdSet(metadata.selectedRouteIds, 'selectedRouteIds');
+  assertCompleteHostedBaselineSelection([...configured], [...selected]);
+  if (!Array.isArray(metadata.expectedCaptures) || metadata.expectedCaptures.length !== configured.size) {
+    throw completeBaselineError(`expected capture metadata does not match ${configured.size} configured route(s).`);
+  }
+
+  const expectedRoutes = new Set();
+  const expectedByIdentity = new Map();
+  for (const expected of metadata.expectedCaptures) {
+    if (!expected || typeof expected !== 'object' || typeof expected.routePath !== 'string' ||
+        !configured.has(expected.routeId) || expectedRoutes.has(expected.routeId)) {
+      throw completeBaselineError(`expected capture metadata has duplicate or extra route "${expected?.routeId || 'unknown'}".`);
+    }
+    expectedRoutes.add(expected.routeId);
+    expectedByIdentity.set(
+      captureIdentityKey(expected, `expected capture "${expected.routeId}"`),
+      expected
+    );
+  }
+
+  if (!Array.isArray(run.captures)) throw completeBaselineError('source run has no captures array.');
+  if (run.captures.length !== expectedByIdentity.size) {
+    throw completeBaselineError(`source run has ${run.captures.length} capture(s), expected ${expectedByIdentity.size}.`);
+  }
+
+  const seen = new Set();
+  const routes = run.captures.map((capture) => {
+    if (!capture || typeof capture !== 'object') {
+      throw completeBaselineError('source run contains a malformed capture.');
+    }
+    const identity = captureIdentityKey(capture, `source capture "${capture.routeId || capture.id || 'unknown'}"`);
+    if (seen.has(identity)) {
+      throw completeBaselineError(`duplicate source route/viewport identity for "${capture.routeId}".`);
+    }
+    seen.add(identity);
+    const expected = expectedByIdentity.get(identity);
+    if (!expected) {
+      throw completeBaselineError(`source run contains an unexpected route/viewport capture for "${capture.routeId}".`);
+    }
+    if (capture.routePath !== expected.routePath) {
+      throw completeBaselineError(`source route "${capture.routeId}" used an unexpected path.`);
+    }
+    if (capture.status !== BASELINE_CAPTURE_SUCCESS_STATUS) {
+      throw completeBaselineError(`source capture "${capture.routeId}" ended with status "${capture.status || 'unknown'}".`);
+    }
+    if (typeof capture.currentObjectKey !== 'string' || !capture.currentObjectKey) {
+      throw completeBaselineError(`source capture "${capture.routeId}" has no currentObjectKey.`);
+    }
+    return {
+      routeId: expected.routeId,
+      routePath: expected.routePath,
+      viewportDescriptorJson: expected.viewportDescriptorJson,
+      objectKey: capture.currentObjectKey
+    };
+  });
+
+  return routes.sort((left, right) => {
+    const leftKey = captureIdentityKey(left, `route "${left.routeId}"`);
+    const rightKey = captureIdentityKey(right, `route "${right.routeId}"`);
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+}
+
+/** @param {string} runId */
+function baselineIdForRun(runId) {
+  return `bsl_${crypto.createHash('sha256').update(runId).digest('hex').slice(0, 24)}`;
+}
+
 /**
  * @param {string | undefined} baseUrl
  * @returns {boolean}
@@ -114,6 +292,33 @@ export function resolveGitRef() {
   };
 }
 
+function resolveHostedBaselinePublicationRef() {
+  const gitRef = resolveGitRef();
+  const refBranch = process.env.GITHUB_REF_NAME || gitRef.refBranch;
+  const refSha = process.env.GITHUB_SHA || gitRef.refSha;
+  const publicationWorkflowRef =
+    process.env.SNAPDRIFT_PUBLICATION_WORKFLOW_REF || process.env.GITHUB_WORKFLOW_REF;
+  const sequenceValue = process.env.SNAPDRIFT_PUBLICATION_SEQUENCE || process.env.GITHUB_RUN_NUMBER;
+  const publicationSequence = Number(sequenceValue);
+  if (
+    !refBranch ||
+    !refSha ||
+    !/^[0-9a-f]{40}$/i.test(refSha) ||
+    !publicationWorkflowRef ||
+    !Number.isSafeInteger(publicationSequence) ||
+    publicationSequence <= 0
+  ) {
+    throw new Error(
+      'Hosted Snap baseline publication requires a branch, a resolved 40-character commit SHA, ' +
+      'a publication workflow identity, and a positive publication sequence. GitHub Actions ' +
+      'provides these as GITHUB_REF_NAME/GITHUB_SHA/GITHUB_WORKFLOW_REF/GITHUB_RUN_NUMBER; ' +
+      'other CI systems may use SNAPDRIFT_PUBLICATION_WORKFLOW_REF and ' +
+      'SNAPDRIFT_PUBLICATION_SEQUENCE.'
+    );
+  }
+  return { refBranch, refSha, publicationWorkflowRef, publicationSequence };
+}
+
 /**
  * Read the package version from package.json.
  * @returns {string}
@@ -329,6 +534,17 @@ export class SnapProvider {
       : splitCommaList(process.env.SNAPDRIFT_ROUTE_IDS);
     const { routes, selectedRouteIds } = selectConfiguredRoutes(config, requestedRouteIds);
     const purpose = options.purpose ?? 'diff';
+    const configuredRouteIds = config.routes.map((route) => route.id);
+    const expectedCaptures = routes.map(expectedCaptureIdentity);
+
+    if (purpose === 'baseline') {
+      assertCompleteHostedBaselineSelection(configuredRouteIds, selectedRouteIds);
+    }
+
+    const baselineRef = purpose === 'baseline' ? resolveHostedBaselinePublicationRef() : undefined;
+    const runContext = baselineRef
+      ? { branch: baselineRef.refBranch, prHeadSha: baselineRef.refSha }
+      : this.#gitRunContext();
 
     if (isLocalBaseUrl(config.baseUrl)) {
       return this.#captureLocalAndUpload({
@@ -338,7 +554,11 @@ export class SnapProvider {
         config,
         routes,
         selectedRouteIds,
-        purpose
+        purpose,
+        configuredRouteIds,
+        expectedCaptures,
+        runContext,
+        baselineRef
       });
     }
 
@@ -355,7 +575,7 @@ export class SnapProvider {
     // Attaching one would make the backend diff the fresh captures against the
     // prior baseline — wasteful at best, and on a dimension mismatch it errors
     // the run and fails the publish.
-    const baselineId = purpose === 'baseline' ? null : await this.#resolveLatestBaselineId();
+    const baselineId = purpose === 'diff' ? await this.#resolveLatestBaselineId() : null;
 
     // We intentionally do NOT send captureProfileJson on run creation. SnapDrift
     // submits routes for server-side rendering, so the render environment
@@ -373,17 +593,27 @@ export class SnapProvider {
       ...(baselineId ? { baselineId } : {}),
       // A baseline run must not be diffed. Suppress the server's
       // auto-resolve-by-branch so no prior baseline is attached.
-      ...(purpose === 'baseline' ? { skipBaselineResolution: true } : {}),
-      ...this.#gitRunContext(),
+      ...(purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
+      capturePlan: {
+        purpose: purpose === 'baseline' ? 'baseline' : 'diff',
+        ...(baselineRef
+          ? {
+              publicationWorkflowRef: baselineRef.publicationWorkflowRef,
+              publicationSequence: baselineRef.publicationSequence
+            }
+          : {}),
+        configuredRouteIds,
+        selectedRouteIds,
+        expectedCaptures
+      },
+      ...runContext,
     }, idempotencyKey);
 
     // Submit each route as a capture with its own idempotency key
     for (const route of routes) {
       const captureKey = this.#generateIdempotencyKey();
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
-      const viewportDescriptor = typeof route.viewport === 'string'
-        ? (VIEWPORT_PRESETS[route.viewport] ?? { width: 1280, height: 720 })
-        : route.viewport;
+      const viewportDescriptor = resolveViewportDescriptor(route.viewport);
       await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
         id: captureId,
         routeId: route.id,
@@ -402,7 +632,17 @@ export class SnapProvider {
     const resultsPath = path.join(outDir, 'results.json');
     const manifestPath = path.join(outDir, 'manifest.json');
 
-    const runMetadata = { runId, projectId: this.#projectId, startedAt: new Date().toISOString() };
+    /** @type {import('../types/visual-diff-types').SnapRunMetadata} */
+    const runMetadata = {
+      runId,
+      projectId: this.#projectId,
+      purpose,
+      ...(baselineRef ? baselineRef : {}),
+      startedAt: new Date().toISOString(),
+      configuredRouteIds,
+      selectedRouteIds,
+      expectedCaptures
+    };
     await Promise.all([
       fs.writeFile(resultsPath, JSON.stringify(runMetadata, null, 2)),
       fs.writeFile(manifestPath, JSON.stringify({
@@ -473,6 +713,7 @@ export class SnapProvider {
     // Snap-native baseline: poll the run that capture() submitted, then
     // create a baseline from the rendered S3 keys.
     if (resultsPath) {
+      /** @type {import('../types/visual-diff-types').SnapRunMetadata | undefined} */
       let metadata;
       /** @type {unknown} */
       let readError;
@@ -482,7 +723,7 @@ export class SnapProvider {
         readError = error;
       }
 
-      if (!metadata?.runId) {
+      if (typeof metadata?.runId !== 'string' || !metadata.runId) {
         // Previously this fell through to a "legacy" branch that POSTed
         // `manifest`/`results` as objects. Snap has never read those fields, so
         // the request could only ever fail — with an opaque 500 before, and with
@@ -501,55 +742,55 @@ export class SnapProvider {
         const { runId } = metadata;
         const idempotencyKey = `baseline-${runId}`;
 
-        // Poll until the run reaches a terminal state (renders + auto-diffs finish)
-        const run = await this.#pollRun(runId);
-
-        if (run.status === 'error') {
-          throw new Error(
-            `Snap baseline run ${runId} ended with status "error" — cannot publish baseline. ` +
-            `Check the snap dashboard for capture error details.`
+        if (!Array.isArray(metadata.expectedCaptures) || metadata.expectedCaptures.length === 0) {
+          throw completeBaselineError(
+            'results metadata has no expected captures; capture again with SnapDrift 0.8.2 or newer.'
           );
         }
 
-        const captures = run.captures ?? [];
-        const rendered = captures.filter((c) => c.currentObjectKey);
+        // Older Snap servers could mark a baseline run terminal after the first
+        // submitted capture. Keep polling until the complete planned capture set
+        // is present and terminal so a mixed-version rollout remains fail-closed.
+        const run = await this.#pollRun(runId, metadata.expectedCaptures.length);
 
-        if (rendered.length === 0) {
+        if (run.id && run.id !== runId) {
           throw new Error(
-            `Snap baseline run ${runId} completed but no captures produced a screenshot ` +
-            `(${captures.length} capture(s) found, 0 rendered). Cannot publish an empty baseline.`
+            `Cannot publish a complete Snap baseline: requested source run ${runId}, but Snap returned ${run.id}.`
           );
         }
 
-        if (rendered.length < captures.length) {
-          const failed = captures.length - rendered.length;
-          process.stderr.write(
-            `[SnapDrift] Warning: ${failed} of ${captures.length} capture(s) did not produce ` +
-            `a screenshot and will be excluded from the baseline.\n`
+        // Hosted baseline runs intentionally use `new` because they omit a
+        // baseline comparison. The server accepts a wider terminal set for
+        // legacy/intentional workflows, but this client is stricter: any other
+        // terminal status means the baseline capture did not establish fresh
+        // ground truth.
+        if (run.status !== BASELINE_RUN_SUCCESS_STATUS) {
+          throw new Error(
+            `Snap baseline run ${runId} ended with status "${run.status || 'unknown'}"; ` +
+            `complete baseline publication requires "${BASELINE_RUN_SUCCESS_STATUS}". ` +
+            'Check the Snap dashboard for capture error details.'
           );
         }
 
-        // Build a manifest from the rendered captures
-        const routes = rendered.map((c) => ({
-            routeId: c.routeId,
-            routePath: c.routePath,
-            viewportDescriptorJson: c.viewportDescriptorJson,
-            objectKey: c.currentObjectKey
-          }));
+        const routes = validateCompleteBaselineRun(metadata, run, this.#projectId);
 
         const manifestJson = JSON.stringify({
           schemaVersion: 1,
           sourceRunId: runId,
+          publicationWorkflowRef: metadata.publicationWorkflowRef,
           routes
         });
 
-        const baselineId = `bsl_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+        const baselineId = baselineIdForRun(runId);
         await this.#request(
           'POST',
           `/v1/visual/projects/${this.#projectId}/baselines`,
           {
             id: baselineId,
-            ...resolveGitRef(),
+            refBranch: metadata.refBranch,
+            refSha: metadata.refSha,
+            publicationMode: 'complete',
+            sourceRunId: runId,
             manifestJson,
             captureProfileJson: JSON.stringify(this.#buildCaptureProfile())
           },
@@ -952,7 +1193,11 @@ export class SnapProvider {
    *   config: VisualRegressionConfig,
    *   routes: VisualRegressionConfig['routes'],
    *   selectedRouteIds: string[],
-   *   purpose: 'baseline' | 'diff'
+   *   purpose: 'baseline' | 'capture' | 'diff',
+   *   configuredRouteIds: string[],
+   *   expectedCaptures: import('../types/visual-diff-types').SnapExpectedCaptureIdentity[],
+   *   runContext: { branch?: string, prHeadSha?: string },
+   *   baselineRef?: { refBranch: string, refSha: string, publicationWorkflowRef: string, publicationSequence: number }
    * }} options
    * @returns {Promise<CaptureResult>}
    */
@@ -985,7 +1230,7 @@ export class SnapProvider {
     // omit the baselineId. Captures then settle to "new" server-side (no
     // comparison), and publishBaseline harvests their object keys. A diff run
     // attaches the latest baseline so the backend can compare against it.
-    const baselineId = options.purpose === 'baseline' ? null : await this.#resolveLatestBaselineId();
+    const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId() : null;
 
     await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
       id: runId,
@@ -994,15 +1239,25 @@ export class SnapProvider {
       ...(baselineId ? { baselineId } : {}),
       // A baseline run must not be diffed. Suppress the server's
       // auto-resolve-by-branch so no prior baseline is attached.
-      ...(options.purpose === 'baseline' ? { skipBaselineResolution: true } : {}),
-      ...this.#gitRunContext()
+      ...(options.purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
+      capturePlan: {
+        purpose: options.purpose === 'baseline' ? 'baseline' : 'diff',
+        ...(options.baselineRef
+          ? {
+              publicationWorkflowRef: options.baselineRef.publicationWorkflowRef,
+              publicationSequence: options.baselineRef.publicationSequence
+            }
+          : {}),
+        configuredRouteIds: options.configuredRouteIds,
+        selectedRouteIds: options.selectedRouteIds,
+        expectedCaptures: options.expectedCaptures
+      },
+      ...options.runContext
     }, this.#generateIdempotencyKey());
 
     for (const { route, manifestEntry } of uploads) {
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
-      const viewportDescriptor = typeof route.viewport === 'string'
-        ? (VIEWPORT_PRESETS[route.viewport] ?? { width: 1280, height: 720 })
-        : route.viewport;
+      const viewportDescriptor = resolveViewportDescriptor(route.viewport);
 
       await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
         id: captureId,
@@ -1032,6 +1287,11 @@ export class SnapProvider {
       captureMode: 'local-upload',
       runId,
       projectId: this.#projectId,
+      purpose: options.purpose,
+      ...(options.baselineRef ? options.baselineRef : {}),
+      configuredRouteIds: options.configuredRouteIds,
+      selectedRouteIds: options.selectedRouteIds,
+      expectedCaptures: options.expectedCaptures,
       snapStartedAt: new Date().toISOString()
     };
     await fs.writeFile(localCapture.resultsPath, JSON.stringify(snapResults, null, 2));
@@ -1210,16 +1470,83 @@ export class SnapProvider {
   /**
    * Poll a run until it reaches a terminal state.
    * @param {string} runId
+   * @param {number} [expectedCaptureCount]
    * @returns {Promise<JsonObject>}
    */
-  async #pollRun(runId) {
+  async #pollRun(runId, expectedCaptureCount) {
     const startTime = Date.now();
+    let incompleteTerminalSignature;
+    let stableIncompleteTerminalPolls = 0;
+    let incompleteSignature;
+    let stableIncompletePolls = 0;
 
     while (Date.now() - startTime < MAX_POLL_DURATION_MS) {
       const run = await this.#request('GET', `/v1/visual/runs/${runId}`);
+      const captures = Array.isArray(run.captures) ? run.captures : [];
+      const completeCaptureSet =
+        expectedCaptureCount === undefined ||
+        (captures.length >= expectedCaptureCount &&
+          captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status)));
+
+      if (expectedCaptureCount !== undefined && !completeCaptureSet) {
+        const signature = JSON.stringify(captures.map((capture) => [
+          capture?.id,
+          capture?.routeId,
+          capture?.status,
+          capture?.currentObjectKey
+        ]).sort((left, right) => {
+          const leftJson = JSON.stringify(left);
+          const rightJson = JSON.stringify(right);
+          return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+        }));
+        if (signature === incompleteSignature) stableIncompletePolls += 1;
+        else {
+          incompleteSignature = signature;
+          stableIncompletePolls = 0;
+        }
+        // A server-side run can remain rendering forever after a cancelled
+        // worker. Do not spend the full ten-minute poll budget on a capture set
+        // that has made no progress for roughly one minute.
+        if (stableIncompletePolls >= MAX_STABLE_INCOMPLETE_POLLS) return run;
+      } else {
+        incompleteSignature = undefined;
+        stableIncompletePolls = 0;
+      }
 
       if (TERMINAL_RUN_STATUSES.has(run.status)) {
-        return run;
+        if (expectedCaptureCount === undefined || run.status === 'error') {
+          return run;
+        }
+
+        if (completeCaptureSet) return run;
+        // An older server can report a terminal run after only an early subset
+        // has settled. Keep polling for the full capture set until the normal
+        // ten-minute deadline; ordinary renders routinely exceed a few seconds.
+        if (
+          captures.length < expectedCaptureCount &&
+          captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status))
+        ) {
+          const signature = JSON.stringify(captures.map((capture) => [
+            capture?.id,
+            capture?.routeId,
+            capture?.status
+          ]).sort((left, right) => {
+            const leftJson = JSON.stringify(left);
+            const rightJson = JSON.stringify(right);
+            return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+          }));
+          if (signature === incompleteTerminalSignature) stableIncompleteTerminalPolls += 1;
+          else {
+            incompleteTerminalSignature = signature;
+            stableIncompleteTerminalPolls = 0;
+          }
+          // A stable terminal subset cannot make render progress. Return it for
+          // precise fail-closed count validation instead of waiting ten minutes.
+          if (stableIncompleteTerminalPolls >= 2) return run;
+        } else {
+          incompleteTerminalSignature = undefined;
+          stableIncompleteTerminalPolls = 0;
+        }
       }
 
       await this.#sleepFn(POLL_INTERVAL_MS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -26,6 +26,7 @@
     "lint": "eslint .",
     "typecheck": "tsc --project tsconfig.json",
     "validate:actions": "node scripts/validate-actions.mjs",
+    "validate:release": "node scripts/validate-release.mjs",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "test:coverage": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage --runInBand",
     "pack:check": "npm pack --dry-run --cache .npm-cache",
@@ -77,6 +78,7 @@
     "./lib/report.mjs": "./lib/report.mjs",
     "./lib/cli.mjs": "./lib/cli.mjs",
     "./lib/provider.mjs": "./lib/provider.mjs",
+    "./lib/outage-policy.mjs": "./lib/outage-policy.mjs",
     "./lib/snap-provider.mjs": "./lib/snap-provider.mjs",
     "./lib/migrate-baselines.mjs": "./lib/migrate-baselines.mjs",
     "./lib/init-from-action.mjs": "./lib/init-from-action.mjs"

package/types/visual-diff-types.d.ts

@@ -74,6 +74,32 @@ export interface VisualBaselineResults {
   passed?: boolean;
 }
 
+/** Exact route/viewport capture identity persisted for hosted baseline validation. */
+export interface SnapExpectedCaptureIdentity {
+  routeId: string;
+  routePath: string;
+  viewportDescriptorJson: string;
+}
+
+/** Metadata written by SnapProvider.capture() and consumed by publishBaseline(). */
+export interface SnapRunMetadata {
+  runId: string;
+  projectId: string;
+  purpose: 'baseline' | 'capture' | 'diff';
+  /** CI source branch for hosted baseline runs; omitted for ordinary diff runs. */
+  refBranch?: string;
+  /** Resolved 40-character CI commit for hosted baseline runs. */
+  refSha?: string;
+  /** Stable CI workflow identity that owns the publication sequence. */
+  publicationWorkflowRef?: string;
+  /** Monotonic CI publication sequence for stale-publisher rejection. */
+  publicationSequence?: number;
+  startedAt: string;
+  configuredRouteIds: string[];
+  selectedRouteIds: string[];
+  expectedCaptures: SnapExpectedCaptureIdentity[];
+}
+
 export interface VisualDiffMissingItem {
   id: string;
   reason: string;