@deeeed/metamask-harness 0.34.1 → 0.34.2

package/library/actions/mobile/perps/performance-capture.mjs

@@ -1,14 +1,21 @@
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import path from 'node:path';
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
 
-const MARKER = '[HomepagePerf]';
-const STATE_FILE = '.homepage-performance-capture.json';
+const MARKER = "[HomepagePerf]";
+const STARTUP_MARKER = "[StartupPerf]";
+const STATE_FILE = ".homepage-performance-capture.json";
+const FRESH_SOURCES = new Set([
+  "fresh_socket",
+  "provider_snapshot",
+  "terminal_global_snapshot_v2",
+  "provider",
+]);
 
 function resolveWithin(root, relativePath, label) {
   const absoluteRoot = path.resolve(root);
   const absolutePath = path.resolve(absoluteRoot, relativePath);
   const relative = path.relative(absoluteRoot, absolutePath);
-  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
     throw new Error(`${label} must stay within ${absoluteRoot}.`);
   }
   return absolutePath;
@@ -18,25 +25,55 @@ async function fileSize(file) {
   try {
     return (await stat(file)).size;
   } catch (error) {
-    if (error?.code === 'ENOENT') return 0;
+    if (error?.code === "ENOENT") return 0;
     throw error;
   }
 }
 
-function parseRecord(line) {
-  const markerIndex = line.indexOf(MARKER);
+function parseRecord(line, marker) {
+  const markerIndex = line.indexOf(marker);
   if (markerIndex < 0) return null;
-  const payload = line.slice(markerIndex + MARKER.length).trim();
+  const payload = line.slice(markerIndex + marker.length).trim();
   try {
     const event = JSON.parse(payload);
-    return event && typeof event === 'object' && !Array.isArray(event) ? event : null;
+    return event && typeof event === "object" && !Array.isArray(event)
+      ? event
+      : null;
   } catch {
     return null;
   }
 }
 
+function startupMeasurements(records) {
+  return records.map((record) => {
+    const processToStageMs = Number(
+      record.process_to_unlock_demand_ms ?? record.process_to_frame_ms,
+    );
+    const unlockToFrameMs = Number(record.unlock_to_frame_ms);
+    const monotonicMs = Number(record.monotonic_ms);
+    const appLaunchEpochMs = Number(record.app_launch_epoch_ms);
+    return {
+      stage: String(record.stage ?? "unknown"),
+      monotonicMs: Number.isFinite(monotonicMs) ? monotonicMs : null,
+      appLaunchEpochMs: Number.isFinite(appLaunchEpochMs)
+        ? appLaunchEpochMs
+        : null,
+      processStartMonotonicMs:
+        Number.isFinite(monotonicMs) && Number.isFinite(processToStageMs)
+          ? roundMs(monotonicMs - processToStageMs)
+          : null,
+      processToStageMs: Number.isFinite(processToStageMs)
+        ? processToStageMs
+        : null,
+      unlockToFrameMs: Number.isFinite(unlockToFrameMs)
+        ? unlockToFrameMs
+        : null,
+    };
+  });
+}
+
 function increment(counts, value) {
-  const key = value == null || value === '' ? 'unknown' : String(value);
+  const key = value == null || value === "" ? "unknown" : String(value);
   counts[key] = (counts[key] ?? 0) + 1;
 }
 
@@ -47,66 +84,227 @@ function roundMs(value) {
 function contentVariantSatisfies(actual, required) {
   if (actual === required) return true;
   return (
-    actual === 'positions_and_orders' &&
-    (required === 'positions' || required === 'orders')
+    actual === "positions_and_orders" &&
+    (required === "positions" || required === "orders")
   );
 }
 
 function requiredFreshStreams(contentVariant, requiredVariants) {
-  if (requiredVariants.length === 0) return ['positions', 'orders'];
+  if (requiredVariants.length === 0) return ["positions", "orders"];
   const streams = new Set();
   for (const required of requiredVariants) {
     if (!contentVariantSatisfies(contentVariant, required)) continue;
-    if (required === 'positions') streams.add('positions');
-    else if (required === 'orders') streams.add('orders');
-    else if (required === 'positions_and_orders') {
-      streams.add('positions');
-      streams.add('orders');
+    if (required === "positions") streams.add("positions");
+    else if (required === "orders") streams.add("orders");
+    else if (required === "positions_and_orders") {
+      streams.add("positions");
+      streams.add("orders");
+    } else if (required === "trending" || required === "pills") {
+      streams.add("positions");
+      streams.add("orders");
+      streams.add("markets");
     } else {
-      // Empty/trending content is derived from both collections.
-      streams.add('positions');
-      streams.add('orders');
+      // Empty content is derived from both account collections.
+      streams.add("positions");
+      streams.add("orders");
     }
   }
   return [...streams];
 }
 
+function frameTime(record) {
+  const value = Number(
+    record.frame_checkpoint_monotonic_ms ?? record.monotonic_ms,
+  );
+  return Number.isFinite(value) ? value : null;
+}
+
+function frameIsFresh(record) {
+  if (record.fresh_for_lifecycle === false) return false;
+  return (
+    FRESH_SOURCES.has(record.source) ||
+    ((record.source === "resident_state" || record.source === "memory_cache") &&
+      FRESH_SOURCES.has(record.origin_source) &&
+      record.fresh_for_lifecycle === true)
+  );
+}
+
+function frameIsCached(record) {
+  return (
+    !frameIsFresh(record) &&
+    ["disk_cache", "memory_cache", "resident_state"].includes(record.source)
+  );
+}
+
+function visibleFrameGroups(records) {
+  const demandLifecycles = new Map(
+    records
+      .filter((record) => record.stage === "viewport_demand")
+      .map((record) => [
+        String(record.demand_id ?? ""),
+        record.lifecycle ?? "unknown",
+      ]),
+  );
+  const groups = new Map();
+  for (const record of records) {
+    if (record.stage !== "next_frame_checkpoint") continue;
+    const at = frameTime(record);
+    if (at === null) continue;
+    const demandId = String(record.demand_id ?? "");
+    const key = `${demandId}:${at}`;
+    const group = groups.get(key) ?? {
+      at,
+      demandId,
+      lifecycle:
+        record.lifecycle ?? demandLifecycles.get(demandId) ?? "unknown",
+      records: [],
+    };
+    group.records.push(record);
+    groups.set(key, group);
+  }
+  return [...groups.values()].sort((left, right) => left.at - right.at);
+}
+
+function frameGroupSatisfies(group, requiredVariants, predicate) {
+  const records = group.records.filter(predicate);
+  const variants = [
+    ...new Set(
+      records
+        .map((record) => String(record.content_variant ?? ""))
+        .filter(Boolean),
+    ),
+  ];
+  const contentMatches =
+    requiredVariants.length === 0 ||
+    requiredVariants.every((required) =>
+      variants.some((actual) => contentVariantSatisfies(actual, required)),
+    );
+  if (!contentMatches) return false;
+  const requiredStreams = requiredFreshStreams(
+    variants[0] ?? "",
+    requiredVariants,
+  );
+  const streams = new Set(records.map((record) => String(record.stream ?? "")));
+  return (
+    requiredStreams.length > 0 &&
+    requiredStreams.every((stream) => streams.has(stream))
+  );
+}
+
+function cacheTakeoverMeasurement(records, requiredContentVariants = []) {
+  const groups = visibleFrameGroups(records);
+  const cached = groups.find((group) =>
+    frameGroupSatisfies(group, requiredContentVariants, frameIsCached),
+  );
+  const fresh = cached
+    ? groups.find(
+        (group) =>
+          group.at > cached.at &&
+          frameGroupSatisfies(group, requiredContentVariants, frameIsFresh),
+      )
+    : null;
+  const cacheHydratedValues = records
+    .filter((record) => record.stage === "disk_cache_hydrated")
+    .map((record) => Number(record.monotonic_ms))
+    .filter(
+      (value) =>
+        Number.isFinite(value) && (cached === undefined || value <= cached.at),
+    );
+  const cacheHydratedAt =
+    cacheHydratedValues.length > 0 ? Math.max(...cacheHydratedValues) : null;
+  const failureReason = !cached
+    ? "missing_cached_visible_frame"
+    : !fresh
+      ? "missing_later_fresh_visible_frame"
+      : cacheHydratedAt === null
+        ? "missing_disk_cache_hydrated"
+        : null;
+  return {
+    status: failureReason === null ? "pass" : "fail",
+    requiredContentVariants: requiredContentVariants,
+    cacheHydratedAtMonotonicMs: cacheHydratedAt,
+    cachedVisibleAtMonotonicMs: cached?.at ?? null,
+    cachedVisibleLifecycle: cached?.lifecycle ?? null,
+    cachedVisibleSources: cached
+      ? [
+          ...new Set(
+            cached.records
+              .filter(frameIsCached)
+              .map((record) => String(record.source)),
+          ),
+        ]
+      : [],
+    freshVisibleAtMonotonicMs: fresh?.at ?? null,
+    freshVisibleLifecycle: fresh?.lifecycle ?? null,
+    cacheToVisibleMs:
+      cached && cacheHydratedAt !== null
+        ? roundMs(cached.at - cacheHydratedAt)
+        : null,
+    cachedToFreshVisibleMs:
+      cached && fresh ? roundMs(fresh.at - cached.at) : null,
+    failureReason,
+  };
+}
+
 function visibleMeasurements(records, requiredFreshContentVariants = []) {
-  const demands = records.filter((record) => record.stage === 'viewport_demand');
+  const demands = records.filter(
+    (record) => record.stage === "viewport_demand",
+  );
   return demands.map((demand) => {
-    const demandId = String(demand.demand_id ?? '');
+    const demandId = String(demand.demand_id ?? "");
     const startedAt = Number(demand.monotonic_ms);
+    const belongsToDemand = (record) =>
+      String(record.demand_id ?? "") === demandId &&
+      ["account_generation", "context_generation"].every(
+        (key) =>
+          demand[key] === undefined ||
+          record[key] === undefined ||
+          String(record[key]) === String(demand[key]),
+      );
     const frames = records.filter(
       (record) =>
-        record.stage === 'next_frame_checkpoint' &&
-        String(record.demand_id ?? '') === demandId,
+        record.stage === "next_frame_checkpoint" && belongsToDemand(record),
+    );
+    const firstVisibleBoundary = records.find(
+      (record) =>
+        record.stage === "first_visible_recorded" && belongsToDemand(record),
+    );
+    const freshVisibleBoundary = records.find(
+      (record) =>
+        record.stage === "fresh_visible_recorded" && belongsToDemand(record),
     );
     const frameTimes = frames
-      .map((record) => Number(record.frame_checkpoint_monotonic_ms ?? record.monotonic_ms))
+      .map((record) =>
+        Number(record.frame_checkpoint_monotonic_ms ?? record.monotonic_ms),
+      )
       .filter(Number.isFinite);
-    const firstVisibleAt = frameTimes.length > 0 ? Math.min(...frameTimes) : null;
+    const recordedFirstVisibleAt = frameTime(firstVisibleBoundary ?? {});
+    const firstVisibleAt =
+      recordedFirstVisibleAt ??
+      (frameTimes.length > 0 ? Math.min(...frameTimes) : null);
     const firstFreshByStream = {};
     const freshStreamsSeen = new Set();
-    let freshVisibleAt = null;
-    let freshContentVariant = null;
+    let freshVisibleAt = frameTime(freshVisibleBoundary ?? {});
+    let freshContentVariant = freshVisibleBoundary?.content_variant ?? null;
     const sortedFrames = [...frames].sort(
       (left, right) =>
         Number(left.frame_checkpoint_monotonic_ms ?? left.monotonic_ms) -
         Number(right.frame_checkpoint_monotonic_ms ?? right.monotonic_ms),
     );
     for (const frame of sortedFrames) {
-      const freshVisible =
-        frame.source === 'fresh_socket' ||
-        (frame.source === 'resident_state' &&
-          frame.origin_source === 'fresh_socket' &&
-          frame.fresh_for_lifecycle === true);
+      const freshVisible = frameIsFresh(frame);
       if (!freshVisible || !frame.stream) continue;
-      const frameAt = Number(frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms);
+      const frameAt = Number(
+        frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms,
+      );
       if (!Number.isFinite(frameAt)) continue;
       const stream = String(frame.stream);
-      firstFreshByStream[stream] = Math.min(firstFreshByStream[stream] ?? frameAt, frameAt);
+      firstFreshByStream[stream] = Math.min(
+        firstFreshByStream[stream] ?? frameAt,
+        frameAt,
+      );
       freshStreamsSeen.add(stream);
-      const contentVariant = String(frame.content_variant ?? '');
+      const contentVariant = String(frame.content_variant ?? "");
       const contentMatches =
         requiredFreshContentVariants.length === 0 ||
         requiredFreshContentVariants.every((required) =>
@@ -134,74 +332,143 @@ function visibleMeasurements(records, requiredFreshContentVariants = []) {
       firstFreshByStream.positions != null &&
       firstFreshByStream.orders != null
     ) {
-      freshVisibleAt = Math.max(firstFreshByStream.positions, firstFreshByStream.orders);
+      freshVisibleAt = Math.max(
+        firstFreshByStream.positions,
+        firstFreshByStream.orders,
+      );
     }
-    const dataAges = frames.map((record) => Number(record.data_age_ms)).filter(Number.isFinite);
+    const dataAges = frames
+      .map((record) => Number(record.data_age_ms))
+      .filter(Number.isFinite);
     return {
       demandId,
-      lifecycle: demand.lifecycle ?? 'unknown',
+      lifecycle: demand.lifecycle ?? "unknown",
       startedAtMonotonicMs: Number.isFinite(startedAt) ? startedAt : null,
       firstVisibleAtMonotonicMs: firstVisibleAt,
-      ttcMs:
-        Number.isFinite(startedAt) && firstVisibleAt != null
+      ttcMs: Number.isFinite(Number(firstVisibleBoundary?.duration_ms))
+        ? roundMs(Number(firstVisibleBoundary.duration_ms))
+        : Number.isFinite(startedAt) && firstVisibleAt != null
           ? roundMs(firstVisibleAt - startedAt)
           : null,
       freshVisibleAtMonotonicMs: freshVisibleAt,
       freshContentVariant,
       dataReadyAtDemand: sortedFrames.some(
-        (frame) =>
-          frame.data_ready_at_demand === true &&
-          (frame.source === 'fresh_socket' ||
-            (frame.origin_source === 'fresh_socket' && frame.fresh_for_lifecycle === true)),
+        (frame) => frame.data_ready_at_demand === true && frameIsFresh(frame),
       ),
-      dfdMs:
-        Number.isFinite(startedAt) && freshVisibleAt != null
+      dfdMs: Number.isFinite(Number(freshVisibleBoundary?.duration_ms))
+        ? roundMs(Number(freshVisibleBoundary.duration_ms))
+        : Number.isFinite(startedAt) && freshVisibleAt != null
           ? roundMs(freshVisibleAt - startedAt)
           : null,
-      deliverySources: [...new Set(frames.map((record) => String(record.source ?? 'unknown')))],
-      contentVariant: frames.find((record) => record.content_variant)?.content_variant ?? null,
+      deliverySources: [
+        ...new Set(frames.map((record) => String(record.source ?? "unknown"))),
+      ],
+      contentVariant:
+        frames.find((record) => record.content_variant)?.content_variant ??
+        null,
       maxDataAgeMs: dataAges.length > 0 ? Math.max(...dataAges) : null,
     };
   });
 }
 
+function percentile(values, fraction) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.max(0, Math.ceil(fraction * sorted.length) - 1)];
+}
+
+function measurementStats(measurements, field) {
+  const rawMs = measurements
+    .map((measurement) => measurement[field])
+    .filter((value) => Number.isFinite(value))
+    .sort((left, right) => left - right);
+  return {
+    successCount: rawMs.length,
+    failureCount: measurements.length - rawMs.length,
+    minMs: rawMs[0] ?? null,
+    p50Ms: percentile(rawMs, 0.5),
+    p75Ms: percentile(rawMs, 0.75),
+    p95Ms: percentile(rawMs, 0.95),
+    maxMs: rawMs.at(-1) ?? null,
+    rawMs,
+  };
+}
+
+function visibleMeasurementCohorts(measurements) {
+  const byLifecycle = new Map();
+  for (const measurement of measurements) {
+    const lifecycle = String(measurement.lifecycle ?? "unknown");
+    const cohort = byLifecycle.get(lifecycle) ?? [];
+    cohort.push(measurement);
+    byLifecycle.set(lifecycle, cohort);
+  }
+  return Object.fromEntries(
+    [...byLifecycle.entries()].map(([lifecycle, cohort]) => {
+      const sourceDistribution = {};
+      for (const measurement of cohort) {
+        for (const source of measurement.deliverySources) {
+          increment(sourceDistribution, source);
+        }
+      }
+      return [
+        lifecycle,
+        {
+          sampleCount: cohort.length,
+          ttc: measurementStats(cohort, "ttcMs"),
+          dfd: measurementStats(cohort, "dfdMs"),
+          sourceDistribution,
+        },
+      ];
+    }),
+  );
+}
+
 function socketPipelineMeasurements(records) {
   const sockets = records.filter(
-    (record) => record.stage === 'socket_received' && record.delivery_id,
+    (record) => record.stage === "socket_received" && record.delivery_id,
   );
   return sockets.flatMap((socket) => {
     const deliveryId = String(socket.delivery_id);
     const socketAt = Number(socket.monotonic_ms);
     const commit = records.find(
-      (record) => record.stage === 'react_commit' && String(record.delivery_id ?? '') === deliveryId,
+      (record) =>
+        record.stage === "react_commit" &&
+        String(record.delivery_id ?? "") === deliveryId,
     );
     const frame = records.find(
-      (record) => record.stage === 'next_frame_checkpoint' && String(record.delivery_id ?? '') === deliveryId,
+      (record) =>
+        record.stage === "next_frame_checkpoint" &&
+        String(record.delivery_id ?? "") === deliveryId,
     );
     if (!commit || !frame || !Number.isFinite(socketAt)) return [];
     const commitAt = Number(commit.monotonic_ms);
-    const frameAt = Number(frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms);
+    const frameAt = Number(
+      frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms,
+    );
     const subscriberCandidates = records
       .filter(
         (record) =>
-          record.stage === 'subscriber_delivery' &&
-          String(record.delivery_id ?? '') === deliveryId &&
+          record.stage === "subscriber_delivery" &&
+          String(record.delivery_id ?? "") === deliveryId &&
           Number(record.monotonic_ms) <= commitAt,
       )
       .map((record) => Number(record.monotonic_ms))
       .filter(Number.isFinite);
-    const subscriberAt = subscriberCandidates.length > 0
-      ? Math.max(...subscriberCandidates)
-      : socketAt;
-    return [{
-      deliveryId,
-      stream: socket.stream ?? null,
-      lifecycle: commit.lifecycle ?? socket.lifecycle ?? 'unknown',
-      socketToVisibleMs: roundMs(frameAt - socketAt),
-      socketToSubscriberMs: roundMs(subscriberAt - socketAt),
-      subscriberToCommitMs: roundMs(commitAt - subscriberAt),
-      commitToFrameMs: roundMs(frameAt - commitAt),
-    }];
+    const subscriberAt =
+      subscriberCandidates.length > 0
+        ? Math.max(...subscriberCandidates)
+        : socketAt;
+    return [
+      {
+        deliveryId,
+        stream: socket.stream ?? null,
+        lifecycle: commit.lifecycle ?? socket.lifecycle ?? "unknown",
+        socketToVisibleMs: roundMs(frameAt - socketAt),
+        socketToSubscriberMs: roundMs(subscriberAt - socketAt),
+        subscriberToCommitMs: roundMs(commitAt - subscriberAt),
+        commitToFrameMs: roundMs(frameAt - commitAt),
+      },
+    ];
   });
 }
 
@@ -218,8 +485,8 @@ function firstFreshDeliveryChecks(records, requirements) {
     );
     const socket = records.find(
       (record) =>
-        record.stage === 'socket_received' &&
-        record.source === 'fresh_socket' &&
+        record.stage === "socket_received" &&
+        record.source === "fresh_socket" &&
         record.stream === stream &&
         (requiredLifecycle === null ||
           record.lifecycle === requiredLifecycle) &&
@@ -228,7 +495,7 @@ function firstFreshDeliveryChecks(records, requirements) {
     const delivery = socket
       ? records.find(
           (record) =>
-            record.stage === 'subscriber_delivery' &&
+            record.stage === "subscriber_delivery" &&
             record.delivery_id === socket.delivery_id &&
             record.stream === stream &&
             record.lifecycle === socket.lifecycle &&
@@ -251,20 +518,25 @@ function firstFreshDeliveryChecks(records, requirements) {
       status:
         socketToSubscriberMs !== null &&
         socketToSubscriberMs <= maxSocketToSubscriberMs
-          ? 'pass'
-          : 'fail',
+          ? "pass"
+          : "fail",
     };
   });
 }
 
 function summarize(
   records,
+  startupRecords,
   sourcePath,
   offset,
   bytesScanned,
   requiredFreshContentVariants = [],
   firstFreshDeliveryRequirements = [],
 ) {
+  const measurements = visibleMeasurements(
+    records,
+    requiredFreshContentVariants,
+  );
   const stages = {};
   const lifecycles = {};
   const streams = {};
@@ -278,6 +550,10 @@ function summarize(
   const monotonicValues = records
     .map((record) => Number(record.monotonic_ms))
     .filter(Number.isFinite);
+  const startupStages = {};
+  for (const record of startupRecords) {
+    increment(startupStages, record.stage);
+  }
   return {
     schemaVersion: 1,
     marker: MARKER,
@@ -285,13 +561,24 @@ function summarize(
     offset,
     bytesScanned,
     recordCount: records.length,
+    startupMarker: STARTUP_MARKER,
+    startupRecordCount: startupRecords.length,
+    startupStages,
+    startupMeasurements: startupMeasurements(startupRecords),
     stages,
     lifecycles,
     streams,
     sources,
-    firstMonotonicMs: monotonicValues.length > 0 ? Math.min(...monotonicValues) : null,
-    lastMonotonicMs: monotonicValues.length > 0 ? Math.max(...monotonicValues) : null,
-    visibleMeasurements: visibleMeasurements(records, requiredFreshContentVariants),
+    firstMonotonicMs:
+      monotonicValues.length > 0 ? Math.min(...monotonicValues) : null,
+    lastMonotonicMs:
+      monotonicValues.length > 0 ? Math.max(...monotonicValues) : null,
+    visibleMeasurements: measurements,
+    visibleMeasurementCohorts: visibleMeasurementCohorts(measurements),
+    cacheTakeoverMeasurement: cacheTakeoverMeasurement(
+      records,
+      requiredFreshContentVariants,
+    ),
     socketPipelineMeasurements: socketPipelineMeasurements(records),
     firstFreshDeliveryChecks: firstFreshDeliveryChecks(
       records,
@@ -302,71 +589,129 @@ function summarize(
 
 export async function captureHomepagePerformance(input) {
   const node = input.node ?? {};
-  const phase = String(node.phase ?? '').toLowerCase();
-  if (phase !== 'start' && phase !== 'end') {
-    throw new Error('metamask.perps.capture_performance requires phase=start or phase=end.');
+  const phase = String(node.phase ?? "").toLowerCase();
+  if (phase !== "start" && phase !== "end") {
+    throw new Error(
+      "metamask.perps.capture_performance requires phase=start or phase=end.",
+    );
   }
 
   const projectRoot = input.context?.projectRoot;
   const artifactsDir = input.context?.artifactsDir;
   if (!projectRoot || !artifactsDir) {
-    throw new Error('metamask.perps.capture_performance requires projectRoot and artifactsDir.');
+    throw new Error(
+      "metamask.perps.capture_performance requires projectRoot and artifactsDir.",
+    );
   }
-  const sourcePath = String(node.source_path ?? 'temp/recipe/runtime/app-console.log');
-  const sourceFile = resolveWithin(projectRoot, sourcePath, 'source_path');
-  const stateFile = resolveWithin(artifactsDir, STATE_FILE, 'capture state');
+  const sourcePath = String(
+    node.source_path ?? "temp/recipe/runtime/app-console.log",
+  );
+  const sourceFile = resolveWithin(projectRoot, sourcePath, "source_path");
+  const stateFile = resolveWithin(artifactsDir, STATE_FILE, "capture state");
   await mkdir(artifactsDir, { recursive: true });
 
-  if (phase === 'start') {
+  if (phase === "start") {
     const offset = await fileSize(sourceFile);
-    await writeFile(stateFile, `${JSON.stringify({ sourcePath, offset }, null, 2)}\n`);
+    await writeFile(
+      stateFile,
+      `${JSON.stringify({ sourcePath, offset }, null, 2)}\n`,
+    );
     return { phase, sourcePath, offset };
   }
 
   let state;
   try {
-    state = JSON.parse(await readFile(stateFile, 'utf8'));
+    state = JSON.parse(await readFile(stateFile, "utf8"));
   } catch (error) {
     throw new Error(
-      'metamask.perps.capture_performance phase=end requires a successful phase=start in the same recipe run.',
+      "metamask.perps.capture_performance phase=end requires a successful phase=start in the same recipe run.",
       { cause: error },
     );
   }
-  if (state.sourcePath !== sourcePath || !Number.isInteger(state.offset) || state.offset < 0) {
-    throw new Error('metamask.perps.capture_performance capture state is invalid or uses a different source_path.');
+  if (
+    state.sourcePath !== sourcePath ||
+    !Number.isInteger(state.offset) ||
+    state.offset < 0
+  ) {
+    throw new Error(
+      "metamask.perps.capture_performance capture state is invalid or uses a different source_path.",
+    );
   }
 
   const content = await readFile(sourceFile);
   const offset = state.offset <= content.length ? state.offset : 0;
-  const segment = content.subarray(offset).toString('utf8');
-  const lines = segment.split(/\r?\n/u).filter((line) => line.includes(MARKER));
-  const records = lines.map(parseRecord).filter(Boolean);
+  const segment = content.subarray(offset).toString("utf8");
+  const lines = segment
+    .split(/\r?\n/u)
+    .filter((line) => line.includes(MARKER) || line.includes(STARTUP_MARKER));
+  const records = lines
+    .filter((line) => line.includes(MARKER))
+    .map((line) => parseRecord(line, MARKER))
+    .filter(Boolean);
+  const startupRecords = lines
+    .filter((line) => line.includes(STARTUP_MARKER))
+    .map((line) => parseRecord(line, STARTUP_MARKER))
+    .filter(Boolean);
   const requireRecords = node.require_records !== false;
   const requiredStages = Array.isArray(node.required_stages)
     ? node.required_stages.map(String)
     : [];
-  const presentStages = new Set(records.map((record) => String(record.stage ?? '')));
-  const missingStages = requiredStages.filter((stage) => !presentStages.has(stage));
+  const presentStages = new Set(
+    records.map((record) => String(record.stage ?? "")),
+  );
+  const missingStages = requiredStages.filter(
+    (stage) => !presentStages.has(stage),
+  );
+  const requiredStartupStages = Array.isArray(node.required_startup_stages)
+    ? node.required_startup_stages.map(String)
+    : [];
+  const presentStartupStages = new Set(
+    startupRecords.map((record) => String(record.stage ?? "")),
+  );
+  const missingStartupStages = requiredStartupStages.filter(
+    (stage) => !presentStartupStages.has(stage),
+  );
   const requiredLifecycles = Array.isArray(node.required_lifecycles)
     ? node.required_lifecycles.map(String)
     : [];
-  const presentLifecycles = new Set(records.map((record) => String(record.lifecycle ?? '')));
+  const presentLifecycles = new Set(
+    records.map((record) => String(record.lifecycle ?? "")),
+  );
   const missingLifecycles = requiredLifecycles.filter(
     (lifecycle) => !presentLifecycles.has(lifecycle),
   );
   const requiredSources = Array.isArray(node.required_sources)
     ? node.required_sources.map(String)
     : [];
-  const presentSources = new Set(records.map((record) => String(record.source ?? '')));
-  const missingSources = requiredSources.filter((source) => !presentSources.has(source));
-  const requiredFreshContentVariants = Array.isArray(node.required_fresh_content_variants)
+  const presentSources = new Set(
+    records.map((record) => String(record.source ?? "")),
+  );
+  const missingSources = requiredSources.filter(
+    (source) => !presentSources.has(source),
+  );
+  const requiredFreshContentVariants = Array.isArray(
+    node.required_fresh_content_variants,
+  )
     ? node.required_fresh_content_variants.map(String)
     : [];
-  const measurements = visibleMeasurements(records, requiredFreshContentVariants);
+  const measurements = visibleMeasurements(
+    records,
+    requiredFreshContentVariants,
+  );
+  const requiredFreshLifecycles = Array.isArray(node.required_fresh_lifecycles)
+    ? node.required_fresh_lifecycles.map(String)
+    : [];
+  const missingFreshLifecycles = requiredFreshLifecycles.filter(
+    (lifecycle) =>
+      !measurements.some(
+        (measurement) =>
+          measurement.lifecycle === lifecycle && measurement.dfdMs !== null,
+      ),
+  );
   const presentFreshContentVariants = new Set(
     measurements
       .filter((measurement) => measurement.dfdMs !== null)
-      .map((measurement) => String(measurement.freshContentVariant ?? '')),
+      .map((measurement) => String(measurement.freshContentVariant ?? "")),
   );
   const missingFreshContentVariants = requiredFreshContentVariants.filter(
     (variant) =>
@@ -384,34 +729,52 @@ export async function captureHomepagePerformance(input) {
     firstFreshDeliveryRequirements,
   );
   const failedFirstFreshDeliveries = deliveryChecks.filter(
-    (check) => check.status === 'fail',
+    (check) => check.status === "fail",
+  );
+  const requireCacheBeforeFresh = node.require_cache_before_fresh === true;
+  const cacheTakeover = cacheTakeoverMeasurement(
+    records,
+    requiredFreshContentVariants,
   );
 
-  const prefix = String(node.artifact_prefix ?? 'logs/homepage-performance');
+  const prefix = String(node.artifact_prefix ?? "logs/homepage-performance");
   const logPath = `${prefix}.log`;
   const summaryPath = `${prefix}-summary.json`;
-  const logFile = resolveWithin(artifactsDir, logPath, 'artifact_prefix');
-  const summaryFile = resolveWithin(artifactsDir, summaryPath, 'artifact_prefix');
+  const logFile = resolveWithin(artifactsDir, logPath, "artifact_prefix");
+  const summaryFile = resolveWithin(
+    artifactsDir,
+    summaryPath,
+    "artifact_prefix",
+  );
   const validation = {
     status:
       (!requireRecords || records.length > 0) &&
       missingStages.length === 0 &&
+      missingStartupStages.length === 0 &&
       missingLifecycles.length === 0 &&
       missingSources.length === 0 &&
+      missingFreshLifecycles.length === 0 &&
       missingFreshContentVariants.length === 0 &&
-      failedFirstFreshDeliveries.length === 0
-        ? 'pass'
-        : 'fail',
+      failedFirstFreshDeliveries.length === 0 &&
+      (!requireCacheBeforeFresh || cacheTakeover.status === "pass")
+        ? "pass"
+        : "fail",
     requireRecords,
     missingStages,
+    missingStartupStages,
     missingLifecycles,
     missingSources,
+    missingFreshLifecycles,
     missingFreshContentVariants,
     failedFirstFreshDeliveries,
+    cacheBeforeFresh: requireCacheBeforeFresh
+      ? cacheTakeover.status
+      : "not_required",
   };
   const summary = {
     ...summarize(
       records,
+      startupRecords,
       sourcePath,
       offset,
       content.length - offset,
@@ -420,37 +783,60 @@ export async function captureHomepagePerformance(input) {
     ),
     validation,
   };
-  const nodeId = String(input.context?.nodeId ?? 'capture-performance');
+  const nodeId = String(input.context?.nodeId ?? "capture-performance");
   await mkdir(path.dirname(logFile), { recursive: true });
-  await writeFile(logFile, lines.length > 0 ? `${lines.join('\n')}\n` : '');
+  await writeFile(logFile, lines.length > 0 ? `${lines.join("\n")}\n` : "");
   await writeFile(summaryFile, `${JSON.stringify(summary, null, 2)}\n`);
   await rm(stateFile, { force: true });
 
   if (requireRecords && records.length === 0) {
-    throw new Error(`No ${MARKER} records were emitted after the capture started.`);
+    throw new Error(
+      `No ${MARKER} records were emitted after the capture started.`,
+    );
   }
   if (missingStages.length > 0) {
-    throw new Error(`Missing required ${MARKER} stages: ${missingStages.join(', ')}.`);
+    throw new Error(
+      `Missing required ${MARKER} stages: ${missingStages.join(", ")}.`,
+    );
+  }
+  if (missingStartupStages.length > 0) {
+    throw new Error(
+      `Missing required ${STARTUP_MARKER} stages: ${missingStartupStages.join(", ")}.`,
+    );
   }
   if (missingLifecycles.length > 0) {
-    throw new Error(`Missing required ${MARKER} lifecycles: ${missingLifecycles.join(', ')}.`);
+    throw new Error(
+      `Missing required ${MARKER} lifecycles: ${missingLifecycles.join(", ")}.`,
+    );
   }
   if (missingSources.length > 0) {
-    throw new Error(`Missing required ${MARKER} sources: ${missingSources.join(', ')}.`);
+    throw new Error(
+      `Missing required ${MARKER} sources: ${missingSources.join(", ")}.`,
+    );
+  }
+  if (missingFreshLifecycles.length > 0) {
+    throw new Error(
+      `Missing required fresh ${MARKER} lifecycles: ${missingFreshLifecycles.join(", ")}.`,
+    );
   }
   if (missingFreshContentVariants.length > 0) {
     throw new Error(
-      `Missing required fresh ${MARKER} content variants: ${missingFreshContentVariants.join(', ')}.`,
+      `Missing required fresh ${MARKER} content variants: ${missingFreshContentVariants.join(", ")}.`,
     );
   }
   if (failedFirstFreshDeliveries.length > 0) {
     const failures = failedFirstFreshDeliveries.map(
       (check) =>
-        `${check.stream}/${check.lifecycle ?? 'any'} throttle=${check.subscriberThrottleMs}ms ` +
-        `measured=${check.socketToSubscriberMs ?? 'missing'}ms max=${check.maxSocketToSubscriberMs}ms`,
+        `${check.stream}/${check.lifecycle ?? "any"} throttle=${check.subscriberThrottleMs}ms ` +
+        `measured=${check.socketToSubscriberMs ?? "missing"}ms max=${check.maxSocketToSubscriberMs}ms`,
     );
     throw new Error(
-      `First fresh ${MARKER} delivery requirements failed: ${failures.join('; ')}.`,
+      `First fresh ${MARKER} delivery requirements failed: ${failures.join("; ")}.`,
+    );
+  }
+  if (requireCacheBeforeFresh && cacheTakeover.status !== "pass") {
+    throw new Error(
+      `Cache-before-fresh ${MARKER} requirement failed: ${cacheTakeover.failureReason}.`,
     );
   }
 
@@ -458,8 +844,8 @@ export async function captureHomepagePerformance(input) {
     phase,
     ...summary,
     artifacts: [
-      { path: logPath, type: 'log', nodeId },
-      { path: summaryPath, type: 'report', nodeId },
+      { path: logPath, type: "log", nodeId },
+      { path: summaryPath, type: "report", nodeId },
     ],
   };
 }