@deeeed/metamask-harness 0.43.0 → 0.44.1

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

@@ -1,4 +1,5 @@
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 const MARKER = "[PerpsPerf]";
@@ -7,12 +8,39 @@ const DETAILED_MARKERS = [MARKER, LEGACY_MARKER];
 const STARTUP_MARKER = "[StartupPerf]";
 const LOAD_PROOF_MARKER = "[PerpsLoadProof]";
 const STATE_FILE = ".homepage-performance-capture.json";
+const CAPTURE_BOUNDARY_BYTES = 4096;
+const BOOTSTRAP_LOOKBACK_BYTES = 512 * 1024;
 const FRESH_SOURCES = new Set([
   "fresh_socket",
   "provider_snapshot",
   "terminal_global_snapshot_v2",
+  "terminal_v2",
   "provider",
 ]);
+const SURFACE_STAGE_ORDER = [
+  "surface_demand",
+  "surface_initial_ui_recorded",
+  "surface_resolved_recorded",
+  "surface_live_recorded",
+];
+const SURFACE_STAGES = new Set(SURFACE_STAGE_ORDER);
+const PERFORMANCE_IDENTITY_FIELDS = [
+  "demand_id",
+  "perps_session_id",
+  "lifecycle",
+  "account_generation",
+  "context_generation",
+];
+const LOAD_PROOF_BASE_IDENTITY_FIELDS = PERFORMANCE_IDENTITY_FIELDS.slice(1);
+const LOAD_PROOF_IDENTITY_FIELDS = [
+  ...LOAD_PROOF_BASE_IDENTITY_FIELDS,
+  "connection_generation",
+];
+const GENERATION_IDENTITY_FIELDS = new Set([
+  "account_generation",
+  "context_generation",
+  "connection_generation",
+]);
 
 function resolveWithin(root, relativePath, label) {
   const absoluteRoot = path.resolve(root);
@@ -24,15 +52,83 @@ function resolveWithin(root, relativePath, label) {
   return absolutePath;
 }
 
-async function fileSize(file) {
+async function fileState(file) {
   try {
-    return (await stat(file)).size;
+    const value = await stat(file);
+    return { size: value.size, device: value.dev, inode: value.ino };
   } catch (error) {
-    if (error?.code === "ENOENT") return 0;
+    if (error?.code === "ENOENT") return null;
     throw error;
   }
 }
 
+async function readFileRange(file, start, length) {
+  if (length === 0) return Buffer.alloc(0);
+  const handle = await open(file, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, start);
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+
+function captureBoundary(content, offset) {
+  const start = Math.max(0, offset - CAPTURE_BOUNDARY_BYTES);
+  const bytes = content.subarray(start, offset);
+  return {
+    start,
+    length: bytes.length,
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+  };
+}
+
+function captureBoundaryBytes(start, bytes) {
+  return {
+    start,
+    length: bytes.length,
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+  };
+}
+
+async function readCaptureSource(sourceFile, state) {
+  const current = await fileState(sourceFile);
+  if (!current) {
+    if (state.offset === 0 && state.sourceIdentity === null) {
+      return Buffer.alloc(0);
+    }
+    throw new Error("Perps performance capture source disappeared after phase=start.");
+  }
+  if (state.sourceIdentity === null) {
+    state.sourceIdentity = current;
+  }
+  if (
+    state.sourceIdentity &&
+    (current.device !== state.sourceIdentity.device ||
+      current.inode !== state.sourceIdentity.inode)
+  ) {
+    throw new Error("Perps performance capture source was replaced after phase=start.");
+  }
+  if (current.size < state.offset) {
+    throw new Error("Perps performance capture source shrank after phase=start.");
+  }
+  const content = await readFile(sourceFile);
+  const boundary = captureBoundary(content, state.offset);
+  if (state.sourceBoundary === null) {
+    state.sourceBoundary = boundary;
+  } else if (
+    boundary.start !== state.sourceBoundary.start ||
+    boundary.length !== state.sourceBoundary.length ||
+    boundary.sha256 !== state.sourceBoundary.sha256
+  ) {
+    throw new Error(
+      "Perps performance capture source was truncated or rewritten after phase=start.",
+    );
+  }
+  return content;
+}
+
 function parseRecord(line, marker) {
   const markerIndex = line.indexOf(marker);
   if (markerIndex < 0) return null;
@@ -56,83 +152,279 @@ function parseDetailedRecord(line) {
   return marker ? parseRecord(line, marker) : null;
 }
 
-function latestPerpsBootstrapStartRecord(content) {
-  return content
-    .split(/\r?\n/u)
-    .filter((line) => line.includes(LOAD_PROOF_MARKER))
-    .map((line) => parseRecord(line, LOAD_PROOF_MARKER))
-    .filter((record) => record?.stage === "perps_bootstrap_start")
-    .at(-1) ?? null;
+function identityField(record, field) {
+  if (field === "perps_session_id") {
+    if (Object.hasOwn(record, "perps_session_id")) {
+      return { present: true, value: record.perps_session_id };
+    }
+    if (Object.hasOwn(record, "session_id")) {
+      return { present: true, value: record.session_id };
+    }
+    return { present: false, value: undefined };
+  }
+  return Object.hasOwn(record, field)
+    ? { present: true, value: record[field] }
+    : { present: false, value: undefined };
+}
+
+function hasValidIdentityField(record, field) {
+  const identity = identityField(record, field);
+  if (
+    !identity.present ||
+    identity.value === null ||
+    identity.value === undefined
+  ) {
+    return false;
+  }
+  if (GENERATION_IDENTITY_FIELDS.has(field)) {
+    return (
+      typeof identity.value === "number" &&
+      Number.isInteger(identity.value) &&
+      identity.value >= 0
+    );
+  }
+  return String(identity.value).trim().length > 0;
+}
+
+function hasCompleteIdentity(record, fields = PERFORMANCE_IDENTITY_FIELDS) {
+  return fields.every((field) => hasValidIdentityField(record, field));
 }
 
-function consoleClockMs(line) {
-  const match = line.match(/\b(\d{2}):(\d{2}):(\d{2})\.(\d{3})\b/u);
-  if (!match) return null;
+function sameIdentity(left, right, fields = PERFORMANCE_IDENTITY_FIELDS) {
   return (
-    Number(match[1]) * 3_600_000 +
-    Number(match[2]) * 60_000 +
-    Number(match[3]) * 1_000 +
-    Number(match[4])
+    hasCompleteIdentity(left, fields) &&
+    hasCompleteIdentity(right, fields) &&
+    fields.every((field) => {
+      const leftField = identityField(left, field);
+      const rightField = identityField(right, field);
+      return String(leftField.value) === String(rightField.value);
+    })
   );
 }
 
-function existingLiveStreamRecords(segmentLines, markerRecords) {
-  let bootstrapLineIndex = -1;
-  segmentLines.forEach((line, index) => {
+function identityKey(record, fields = PERFORMANCE_IDENTITY_FIELDS) {
+  return JSON.stringify(
+    fields.map((field) => {
+      const value = identityField(record, field);
+      return value.present ? [field, String(value.value)] : [field, "<missing>"];
+    }),
+  );
+}
+
+function performanceRecordTime(record) {
+  const value = Number(
+    record.frame_checkpoint_monotonic_ms ?? record.monotonic_ms,
+  );
+  return Number.isFinite(value) ? value : null;
+}
+
+function isAccountContentVariant(value) {
+  return ["positions", "orders", "positions_and_orders"].includes(
+    String(value ?? ""),
+  );
+}
+
+function orderedSurfaceSequence(records, demand, requiredStages) {
+  const stages = SURFACE_STAGE_ORDER.filter((stage) =>
+    requiredStages.includes(stage),
+  );
+  if (stages.length === 0) return [demand];
+  const demandAt = performanceRecordTime(demand);
+  if (demandAt === null) return null;
+  const sequence = [];
+  let previousAt = demandAt;
+  for (const stage of stages) {
+    if (stage === "surface_demand") {
+      sequence.push(demand);
+      continue;
+    }
+    const matches = records
+      .filter(
+        (record) =>
+          record.stage === stage &&
+          sameIdentity(record, demand),
+      )
+      .sort(
+        (left, right) =>
+          performanceRecordTime(left) - performanceRecordTime(right),
+      );
+    if (matches.length !== 1) return null;
+    const match = matches[0];
+    const matchAt = performanceRecordTime(match);
     if (
-      line.includes(LOAD_PROOF_MARKER) &&
-      line.includes('"stage":"perps_bootstrap_start"')
+      matchAt === null ||
+      matchAt < previousAt ||
+      !Number.isFinite(Number(match.duration_ms)) ||
+      Number(match.duration_ms) < 0 ||
+      (stage === "surface_live_recorded" &&
+        (match.fresh_for_lifecycle !== true || !frameIsFresh(match)))
     ) {
-      bootstrapLineIndex = index;
+      return null;
     }
-  });
-  const bootstrapLine =
-    bootstrapLineIndex >= 0 ? segmentLines[bootstrapLineIndex] : undefined;
-  const liveLines =
-    bootstrapLineIndex >= 0
-      ? segmentLines.slice(bootstrapLineIndex + 1)
-      : segmentLines;
-  const bootstrapClock = bootstrapLine ? consoleClockMs(bootstrapLine) : null;
-  const bootstrapRecord = markerRecords
-    .filter((record) => record.stage === "perps_bootstrap_start")
-    .at(-1);
-  const patterns = new Map([
-    ["PerpsWS: First price data received", "prices"],
-    ["PerpsWS: First position data received", "positions"],
-    ["PerpsWS: First order data received", "orders"],
-    ["PerpsWS: First account data received", "account"],
-  ]);
-  const records = [];
-  for (const [message, stream] of patterns) {
-    const line = liveLines.find((candidate) => candidate.includes(message));
-    if (!line) continue;
-    const eventClock = consoleClockMs(line);
-    let elapsedMs = null;
-    if (bootstrapClock !== null && eventClock !== null) {
-      elapsedMs = eventClock - bootstrapClock;
-      if (elapsedMs < 0) elapsedMs += 24 * 3_600_000;
+    sequence.push(match);
+    previousAt = matchAt;
+  }
+  return sequence;
+}
+
+function coherentPerformanceProof(
+  records,
+  loadProofRecords,
+  requiredStages,
+  requiredLiveStreams,
+  expectedLifecycle = null,
+  expectedContentVariant = null,
+) {
+  const requiredSurfaceStages = requiredStages.filter((stage) =>
+    SURFACE_STAGES.has(stage),
+  );
+  const required =
+    requiredSurfaceStages.length > 0 || requiredLiveStreams.length > 0;
+  if (!required) {
+    return {
+      status: "not_required",
+      demand: null,
+      identity: null,
+      missingLiveStreams: [],
+      sequence: [],
+    };
+  }
+  const demands = records.filter((record) => record.stage === "surface_demand");
+  let best = null;
+  for (const demand of demands) {
+    if (!hasCompleteIdentity(demand)) continue;
+    if (
+      records.filter(
+        (record) =>
+          record.stage === "surface_demand" && sameIdentity(record, demand),
+      ).length !== 1
+    ) {
+      continue;
     }
-    records.push({
-      stage: "values_ready",
-      stream,
-      source: "fresh_socket",
-      item_count: null,
-      elapsed_ms: elapsedMs,
-      monotonic_ms:
-        elapsedMs !== null &&
-        Number.isFinite(Number(bootstrapRecord?.monotonic_ms))
-          ? Number(bootstrapRecord.monotonic_ms) + elapsedMs
-          : null,
-      evidence: "existing_sentry_ws_marker",
-    });
+    if (
+      expectedLifecycle !== null &&
+      String(demand.lifecycle ?? "") !== expectedLifecycle
+    ) {
+      continue;
+    }
+    const sequence = orderedSurfaceSequence(
+      records,
+      demand,
+      requiredSurfaceStages,
+    );
+    if (!sequence) continue;
+    if (
+      expectedContentVariant !== null &&
+      sequence
+        .filter((record) => record.stage !== "surface_demand")
+        .some(
+          (record) =>
+            !contentVariantSatisfies(
+              String(record.content_variant ?? ""),
+              expectedContentVariant,
+            ),
+        )
+    ) {
+      continue;
+    }
+    const liveRecords = loadProofRecords.filter(
+      (record) =>
+        record.stage === "values_ready" &&
+        record.source === "fresh_socket" &&
+        hasCompleteIdentity(record, LOAD_PROOF_IDENTITY_FIELDS) &&
+        sameIdentity(record, demand, LOAD_PROOF_BASE_IDENTITY_FIELDS),
+    );
+    const connectionGenerations = new Set(
+      liveRecords.map((record) => record.connection_generation),
+    );
+    const liveRecordConnectionGeneration =
+      connectionGenerations.size === 1
+        ? [...connectionGenerations][0]
+        : null;
+    const liveSurface = sequence.find(
+      (record) => record.stage === "surface_live_recorded",
+    );
+    const accountLiveSurface =
+      liveSurface && isAccountContentVariant(liveSurface.content_variant)
+        ? liveSurface
+        : null;
+    const surfaceConnectionGeneration =
+      accountLiveSurface &&
+      hasValidIdentityField(accountLiveSurface, "connection_generation")
+        ? accountLiveSurface.connection_generation
+        : null;
+    const identityCoherent =
+      connectionGenerations.size <= 1 &&
+      (!accountLiveSurface ||
+        (surfaceConnectionGeneration !== null &&
+          (liveRecordConnectionGeneration === null ||
+            surfaceConnectionGeneration === liveRecordConnectionGeneration)));
+    const coherentConnectionGeneration =
+      liveRecordConnectionGeneration ?? surfaceConnectionGeneration;
+    const liveStreams = new Set(
+      liveRecordConnectionGeneration === null
+        ? []
+        : liveRecords.map((record) => String(record.stream ?? "")),
+    );
+    const missingLiveStreams = requiredLiveStreams.filter(
+      (stream) => !liveStreams.has(stream),
+    );
+    const candidate = {
+      demand,
+      sequence,
+      missingLiveStreams,
+      identityCoherent,
+      connectionGeneration: coherentConnectionGeneration,
+    };
+    if (
+      !best ||
+      Number(identityCoherent) > Number(best.identityCoherent) ||
+      (identityCoherent === best.identityCoherent &&
+        missingLiveStreams.length < best.missingLiveStreams.length)
+    ) {
+      best = candidate;
+    }
+    if (identityCoherent && missingLiveStreams.length === 0) break;
   }
-  return records;
+  return {
+    status:
+      best?.identityCoherent && best.missingLiveStreams.length === 0
+        ? "pass"
+        : "fail",
+    demand: best?.demand ?? null,
+    identity: best
+      ? {
+          ...Object.fromEntries(
+            PERFORMANCE_IDENTITY_FIELDS.map((field) => {
+              const value = identityField(best.demand, field);
+              return [field, value.present ? value.value : null];
+            }),
+          ),
+          connection_generation: best.connectionGeneration,
+        }
+      : null,
+    missingLiveStreams: best?.missingLiveStreams ?? requiredLiveStreams,
+    sequence: best?.sequence.map((record) => record.stage) ?? [],
+  };
+}
+
+function latestPerpsBootstrapStartRecord(content) {
+  return content
+    .split(/\r?\n/u)
+    .filter((line) => line.includes(LOAD_PROOF_MARKER))
+    .map((line) => parseRecord(line, LOAD_PROOF_MARKER))
+    .filter((record) => record?.stage === "perps_bootstrap_start")
+    .at(-1) ?? null;
 }
 
 function mergeLoadProofRecords(records) {
   const byStageStreamSource = new Map();
   for (const record of records) {
-    const key = `${record.stage ?? "unknown"}:${record.stream ?? ""}:${record.source ?? ""}`;
+    const identityFields =
+      record.stage === "values_ready"
+        ? LOAD_PROOF_IDENTITY_FIELDS
+        : LOAD_PROOF_BASE_IDENTITY_FIELDS;
+    const key = `${record.stage ?? "unknown"}:${record.stream ?? ""}:${record.source ?? ""}:${identityKey(record, identityFields)}`;
     const current = byStageStreamSource.get(key);
     if (record.stage === "perps_bootstrap_start") {
       if (
@@ -143,14 +435,9 @@ function mergeLoadProofRecords(records) {
       }
       continue;
     }
-    const recordIsFallback =
-      record.evidence === "existing_sentry_ws_marker";
-    const currentIsFallback =
-      current?.evidence === "existing_sentry_ws_marker";
     const recordElapsedMs = Number(record.elapsed_ms);
     const currentElapsedMs = Number(current?.elapsed_ms);
-    const sameEvidenceClassEarlier =
-      recordIsFallback === currentIsFallback &&
+    const earlier =
       record.elapsed_ms !== null &&
       record.elapsed_ms !== undefined &&
       Number.isFinite(recordElapsedMs) &&
@@ -158,18 +445,14 @@ function mergeLoadProofRecords(records) {
       current?.elapsed_ms !== undefined &&
       Number.isFinite(currentElapsedMs) &&
       recordElapsedMs < currentElapsedMs;
-    if (
-      !current ||
-      (currentIsFallback && !recordIsFallback) ||
-      sameEvidenceClassEarlier
-    ) {
+    if (!current || earlier) {
       byStageStreamSource.set(key, record);
     }
   }
   return [...byStageStreamSource.values()];
 }
 
-async function waitForPerformanceRecord({ node, sourceFile, offset }) {
+async function waitForPerformanceRecord({ node, sourceFile, state }) {
   const stage = node.wait_for_stage;
   const requiredLiveStreams = Array.isArray(node.required_live_streams)
     ? node.required_live_streams.map(String)
@@ -187,6 +470,9 @@ async function waitForPerformanceRecord({ node, sourceFile, offset }) {
           ...(node.wait_for_lifecycle !== undefined
             ? { lifecycle: String(node.wait_for_lifecycle) }
             : {}),
+          ...(node.wait_for_content_variant !== undefined
+            ? { content_variant: String(node.wait_for_content_variant) }
+            : {}),
         };
   const timeoutMs = Math.max(1, Number(node.wait_timeout_ms ?? 60_000));
   const pollIntervalMs = Math.max(
@@ -196,8 +482,8 @@ async function waitForPerformanceRecord({ node, sourceFile, offset }) {
   const deadline = Date.now() + timeoutMs;
 
   while (true) {
-    const content = await readFile(sourceFile);
-    const start = offset <= content.length ? offset : 0;
+    const content = await readCaptureSource(sourceFile, state);
+    const start = state.offset;
     const segmentLines = content
       .subarray(start)
       .toString("utf8")
@@ -206,33 +492,42 @@ async function waitForPerformanceRecord({ node, sourceFile, offset }) {
       .filter(detailedMarker)
       .map(parseDetailedRecord)
       .filter(Boolean);
-    const stageMatched =
-      expected === null ||
-      performanceRecords.some((record) =>
-        Object.entries(expected).every(
-          ([key, value]) => String(record[key] ?? "") === value,
-        ),
-      );
     const markerLoadProofRecords = segmentLines
       .filter((line) => line.includes(LOAD_PROOF_MARKER))
       .map((line) => parseRecord(line, LOAD_PROOF_MARKER))
       .filter(Boolean);
-    const liveStreams = new Set(
-      mergeLoadProofRecords([
-        ...markerLoadProofRecords,
-        ...existingLiveStreamRecords(segmentLines, markerLoadProofRecords),
-      ])
-        .filter(
-          (record) =>
-            record.stage === "values_ready" &&
-            record.source === "fresh_socket",
-        )
-        .map((record) => String(record.stream ?? "")),
-    );
-    const liveStreamsMatched = requiredLiveStreams.every((stream) =>
-      liveStreams.has(stream),
+    const loadProofRecords = mergeLoadProofRecords(markerLoadProofRecords);
+    const coherentProof = coherentPerformanceProof(
+      performanceRecords,
+      loadProofRecords,
+      expected && SURFACE_STAGES.has(expected.stage) ? [expected.stage] : [],
+      requiredLiveStreams,
+      node.wait_for_lifecycle === undefined
+        ? null
+        : String(node.wait_for_lifecycle),
+      node.wait_for_content_variant === undefined
+        ? null
+        : String(node.wait_for_content_variant),
     );
-    if (stageMatched && liveStreamsMatched) return;
+    const stageMatched =
+      expected === null ||
+      performanceRecords.some(
+        (record) =>
+          Object.entries(expected).every(
+            ([key, value]) =>
+              key === "content_variant"
+                ? contentVariantSatisfies(
+                    String(record.content_variant ?? ""),
+                    value,
+                  )
+                : String(record[key] ?? "") === value,
+          ) &&
+          (coherentProof.demand === null ||
+            sameIdentity(record, coherentProof.demand)),
+      );
+    const coherenceMatched =
+      coherentProof.status === "not_required" || coherentProof.status === "pass";
+    if (stageMatched && coherenceMatched) return;
     if (Date.now() >= deadline) {
       throw new Error(
         `Timed out waiting ${timeoutMs}ms for ${MARKER} stage ${JSON.stringify(expected)} and live streams ${JSON.stringify(requiredLiveStreams)}.`,
@@ -271,13 +566,19 @@ function startupMeasurements(records) {
 }
 
 function perpsBootstrapBoundary(homepageRecords, loadProofRecords) {
-  const demandTimes = homepageRecords
+  const demands = homepageRecords
     .filter((record) => record.stage === "surface_demand")
-    .map((record) => Number(record.monotonic_ms))
-    .filter(Number.isFinite);
-  const firstDemandAt = demandTimes.length > 0 ? Math.min(...demandTimes) : null;
+    .filter((record) => Number.isFinite(Number(record.monotonic_ms)))
+    .sort((left, right) => Number(left.monotonic_ms) - Number(right.monotonic_ms));
+  const demand = demands[0] ?? null;
+  const firstDemandAt = demand === null ? null : Number(demand.monotonic_ms);
   const bootstrapTimes = loadProofRecords
-    .filter((record) => record.stage === "perps_bootstrap_start")
+    .filter(
+      (record) =>
+        record.stage === "perps_bootstrap_start" &&
+        demand !== null &&
+        sameIdentity(record, demand, LOAD_PROOF_BASE_IDENTITY_FIELDS),
+    )
     .map((record) => Number(record.monotonic_ms))
     .filter(
       (value) =>
@@ -379,6 +680,13 @@ function frameTime(record) {
 
 function frameIsFresh(record) {
   if (record.fresh_for_lifecycle === false) return false;
+  if (record.source === "retained_market_context") {
+    return (
+      record.lifecycle === "account_switch" &&
+      !isAccountContentVariant(record.content_variant) &&
+      record.fresh_for_lifecycle === true
+    );
+  }
   return (
     FRESH_SOURCES.has(record.source) ||
     ((record.source === "resident_state" || record.source === "memory_cache") &&
@@ -395,13 +703,8 @@ function frameIsCached(record) {
 }
 
 function visibleFrameGroups(records) {
-  const demandLifecycles = new Map(
-    records
-      .filter((record) => record.stage === "surface_demand")
-      .map((record) => [
-        String(record.demand_id ?? ""),
-        record.lifecycle ?? "unknown",
-      ]),
+  const demands = records.filter(
+    (record) => record.stage === "surface_demand",
   );
   const groups = new Map();
   for (const record of records) {
@@ -409,12 +712,13 @@ function visibleFrameGroups(records) {
     const at = frameTime(record);
     if (at === null) continue;
     const demandId = String(record.demand_id ?? "");
-    const key = `${demandId}:${at}`;
+    const key = `${identityKey(record)}:${at}`;
+    const demand = demands.find((candidate) => sameIdentity(candidate, record));
     const group = groups.get(key) ?? {
       at,
       demandId,
-      lifecycle:
-        record.lifecycle ?? demandLifecycles.get(demandId) ?? "unknown",
+      demand,
+      lifecycle: record.lifecycle ?? demand?.lifecycle ?? "unknown",
       records: [],
     };
     group.records.push(record);
@@ -451,23 +755,29 @@ function frameGroupSatisfies(group, requiredVariants, predicate) {
 
 function cacheTakeoverMeasurement(records, requiredContentVariants = []) {
   const groups = visibleFrameGroups(records);
-  const cached = groups.find((group) =>
-    frameGroupSatisfies(group, requiredContentVariants, frameIsCached),
+  const cached = groups.find(
+    (group) =>
+      group.demand &&
+      frameGroupSatisfies(group, requiredContentVariants, frameIsCached),
   );
   const fresh = cached
     ? groups.find(
         (group) =>
           group.at > cached.at &&
+          group.demand &&
+          sameIdentity(group.demand, cached.demand) &&
           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),
-    );
+      (record) =>
+        record.stage === "disk_cache_hydrated" &&
+        cached !== undefined &&
+        sameIdentity(record, cached.demand),
+    )
+    .map((record) => Number(record.monotonic_ms))
+    .filter((value) => Number.isFinite(value) && value <= cached.at);
   const cacheHydratedAt =
     cacheHydratedValues.length > 0 ? Math.max(...cacheHydratedValues) : null;
   const failureReason = !cached
@@ -511,29 +821,42 @@ function visibleMeasurements(records, requiredFreshContentVariants = []) {
   return demands.map((demand) => {
     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 belongsToDemand = (record) => sameIdentity(record, demand);
+    const afterDemand = (record) => {
+      const at = performanceRecordTime(record);
+      return at !== null && Number.isFinite(startedAt) && at >= startedAt;
+    };
     const frames = records.filter(
       (record) =>
-        record.stage === "next_frame_checkpoint" && belongsToDemand(record),
+        record.stage === "next_frame_checkpoint" &&
+        belongsToDemand(record) &&
+        afterDemand(record),
     );
     const commits = records.filter(
-      (record) => record.stage === "react_commit" && belongsToDemand(record),
-    );
-    const firstVisibleBoundary = records.find(
-      (record) =>
-        record.stage === "surface_resolved_recorded" && belongsToDemand(record),
-    );
-    const freshVisibleBoundary = records.find(
       (record) =>
-        record.stage === "surface_live_recorded" && belongsToDemand(record),
+        record.stage === "react_commit" &&
+        belongsToDemand(record) &&
+        afterDemand(record),
     );
+    const firstVisibleBoundary = records
+      .filter(
+        (record) =>
+          record.stage === "surface_resolved_recorded" &&
+          belongsToDemand(record) &&
+          afterDemand(record),
+      )
+      .sort((left, right) => frameTime(left) - frameTime(right))[0];
+    const firstVisibleBoundaryAt = frameTime(firstVisibleBoundary ?? {});
+    const freshVisibleBoundary = records
+      .filter(
+        (record) =>
+          record.stage === "surface_live_recorded" &&
+          belongsToDemand(record) &&
+          afterDemand(record) &&
+          (firstVisibleBoundaryAt === null ||
+            frameTime(record) >= firstVisibleBoundaryAt),
+      )
+      .sort((left, right) => frameTime(left) - frameTime(right))[0];
     const frameTimes = frames
       .map((record) =>
         Number(record.frame_checkpoint_monotonic_ms ?? record.monotonic_ms),
@@ -601,6 +924,11 @@ function visibleMeasurements(records, requiredFreshContentVariants = []) {
     const dataAges = frames
       .map((record) => Number(record.data_age_ms))
       .filter(Number.isFinite);
+    const deliveryRecords = [
+      ...frames,
+      firstVisibleBoundary,
+      freshVisibleBoundary,
+    ].filter(Boolean);
     return {
       demandId,
       lifecycle: demand.lifecycle ?? "unknown",
@@ -625,10 +953,15 @@ function visibleMeasurements(records, requiredFreshContentVariants = []) {
           ? roundMs(freshVisibleAt - startedAt)
           : null,
       deliverySources: [
-        ...new Set(frames.map((record) => String(record.source ?? "unknown"))),
+        ...new Set(
+          deliveryRecords
+            .map((record) => String(record.source ?? ""))
+            .filter(Boolean),
+        ),
       ],
       contentVariant:
-        frames.find((record) => record.content_variant)?.content_variant ??
+        deliveryRecords.find((record) => record.content_variant)
+          ?.content_variant ??
         null,
       maxDataAgeMs: dataAges.length > 0 ? Math.max(...dataAges) : null,
     };
@@ -694,18 +1027,31 @@ function socketPipelineMeasurements(records) {
   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,
-    );
-    const frame = records.find(
-      (record) =>
-        record.stage === "next_frame_checkpoint" &&
-        String(record.delivery_id ?? "") === deliveryId,
-    );
-    if (!commit || !frame || !Number.isFinite(socketAt)) return [];
+    if (!Number.isFinite(socketAt)) return [];
+    const commit = records
+      .filter(
+        (record) =>
+          record.stage === "react_commit" &&
+          String(record.delivery_id ?? "") === deliveryId &&
+          sameIdentity(record, socket) &&
+          Number(record.monotonic_ms) >= socketAt,
+      )
+      .sort(
+        (left, right) => Number(left.monotonic_ms) - Number(right.monotonic_ms),
+      )[0];
+    if (!commit) return [];
     const commitAt = Number(commit.monotonic_ms);
+    const frame = records
+      .filter(
+        (record) =>
+          record.stage === "next_frame_checkpoint" &&
+          String(record.delivery_id ?? "") === deliveryId &&
+          sameIdentity(record, socket) &&
+          frameTime(record) !== null &&
+          frameTime(record) >= commitAt,
+      )
+      .sort((left, right) => frameTime(left) - frameTime(right))[0];
+    if (!frame) return [];
     const frameAt = Number(
       frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms,
     );
@@ -714,14 +1060,14 @@ function socketPipelineMeasurements(records) {
         (record) =>
           record.stage === "subscriber_delivery" &&
           String(record.delivery_id ?? "") === deliveryId &&
+          sameIdentity(record, socket) &&
+          Number(record.monotonic_ms) >= socketAt &&
           Number(record.monotonic_ms) <= commitAt,
       )
       .map((record) => Number(record.monotonic_ms))
       .filter(Number.isFinite);
-    const subscriberAt =
-      subscriberCandidates.length > 0
-        ? Math.max(...subscriberCandidates)
-        : socketAt;
+    if (subscriberCandidates.length === 0) return [];
+    const subscriberAt = Math.max(...subscriberCandidates);
     return [
       {
         deliveryId,
@@ -757,14 +1103,20 @@ function firstFreshDeliveryChecks(records, requirements) {
         record.delivery_id,
     );
     const delivery = socket
-      ? records.find(
-          (record) =>
-            record.stage === "subscriber_delivery" &&
-            record.delivery_id === socket.delivery_id &&
-            record.stream === stream &&
-            record.lifecycle === socket.lifecycle &&
-            Number(record.throttle_ms ?? 0) === subscriberThrottleMs,
-        )
+      ? records
+          .filter(
+            (record) =>
+              record.stage === "subscriber_delivery" &&
+              record.delivery_id === socket.delivery_id &&
+              record.stream === stream &&
+              sameIdentity(record, socket) &&
+              Number(record.monotonic_ms) >= Number(socket.monotonic_ms) &&
+              Number(record.throttle_ms ?? 0) === subscriberThrottleMs,
+          )
+          .sort(
+            (left, right) =>
+              Number(left.monotonic_ms) - Number(right.monotonic_ms),
+          )[0]
       : null;
     const socketAt = Number(socket?.monotonic_ms);
     const subscriberAt = Number(delivery?.monotonic_ms);
@@ -797,6 +1149,7 @@ function summarize(
   bytesScanned,
   requiredFreshContentVariants = [],
   firstFreshDeliveryRequirements = [],
+  includeCacheTakeover = false,
 ) {
   const measurements = visibleMeasurements(
     records,
@@ -849,10 +1202,9 @@ function summarize(
       monotonicValues.length > 0 ? Math.max(...monotonicValues) : null,
     visibleMeasurements: measurements,
     visibleMeasurementCohorts: visibleMeasurementCohorts(measurements),
-    cacheTakeoverMeasurement: cacheTakeoverMeasurement(
-      records,
-      requiredFreshContentVariants,
-    ),
+    cacheTakeoverMeasurement: includeCacheTakeover
+      ? cacheTakeoverMeasurement(records, requiredFreshContentVariants)
+      : { status: "not_required" },
     socketPipelineMeasurements: socketPipelineMeasurements(records),
     firstFreshDeliveryChecks: firstFreshDeliveryChecks(
       records,
@@ -885,15 +1237,29 @@ export async function capturePerpsPerformance(input) {
   await mkdir(artifactsDir, { recursive: true });
 
   if (phase === "start") {
-    const offset = await fileSize(sourceFile);
-    const existingContent =
-      offset > 0 ? (await readFile(sourceFile)).toString("utf8") : "";
+    const sourceIdentity = await fileState(sourceFile);
+    const offset = sourceIdentity?.size ?? 0;
+    const lookbackStart = Math.max(0, offset - BOOTSTRAP_LOOKBACK_BYTES);
+    const existingContent = sourceIdentity
+      ? (
+          await readFileRange(sourceFile, lookbackStart, offset - lookbackStart)
+        ).toString("utf8")
+      : "";
+    const boundaryStart = Math.max(0, offset - CAPTURE_BOUNDARY_BYTES);
+    const sourceBoundary = sourceIdentity
+      ? captureBoundaryBytes(
+          boundaryStart,
+          await readFileRange(sourceFile, boundaryStart, offset - boundaryStart),
+        )
+      : null;
     await writeFile(
       stateFile,
       `${JSON.stringify(
         {
           sourcePath,
           offset,
+          sourceIdentity,
+          sourceBoundary,
           captureStartedAtEpochMs: Date.now(),
           perpsBootstrapStartRecord:
             latestPerpsBootstrapStartRecord(existingContent),
@@ -918,6 +1284,19 @@ export async function capturePerpsPerformance(input) {
     state.sourcePath !== sourcePath ||
     !Number.isInteger(state.offset) ||
     state.offset < 0 ||
+    !(
+      state.sourceIdentity === null ||
+      (state.sourceIdentity &&
+        Number.isInteger(state.sourceIdentity.device) &&
+        Number.isInteger(state.sourceIdentity.inode))
+    ) ||
+    !(
+      state.sourceBoundary === null ||
+      (state.sourceBoundary &&
+        Number.isInteger(state.sourceBoundary.start) &&
+        Number.isInteger(state.sourceBoundary.length) &&
+        typeof state.sourceBoundary.sha256 === "string")
+    ) ||
     !Number.isFinite(state.captureStartedAtEpochMs)
   ) {
     throw new Error(
@@ -928,11 +1307,11 @@ export async function capturePerpsPerformance(input) {
   await waitForPerformanceRecord({
     node,
     sourceFile,
-    offset: state.offset,
+    state,
   });
 
-  const content = await readFile(sourceFile);
-  const offset = state.offset <= content.length ? state.offset : 0;
+  const content = await readCaptureSource(sourceFile, state);
+  const offset = state.offset;
   const segment = content.subarray(offset).toString("utf8");
   const segmentLines = segment.split(/\r?\n/u);
   const lines = segmentLines
@@ -959,10 +1338,7 @@ export async function capturePerpsPerformance(input) {
       .map((line) => parseRecord(line, LOAD_PROOF_MARKER))
       .filter(Boolean),
   ];
-  const loadProofRecords = mergeLoadProofRecords([
-    ...markerLoadProofRecords,
-    ...existingLiveStreamRecords(segmentLines, markerLoadProofRecords),
-  ]);
+  const loadProofRecords = mergeLoadProofRecords(markerLoadProofRecords);
   const requireRecords = node.require_records !== false;
   const requiredStages = Array.isArray(node.required_stages)
     ? node.required_stages.map(String)
@@ -1048,17 +1424,19 @@ export async function capturePerpsPerformance(input) {
   const requiredLiveStreams = Array.isArray(node.required_live_streams)
     ? node.required_live_streams.map(String)
     : [];
-  const presentLiveStreams = new Set(
-    loadProofRecords
-      .filter(
-        (record) =>
-          record.stage === "values_ready" && record.source === "fresh_socket",
-      )
-      .map((record) => String(record.stream ?? "")),
-  );
-  const missingLiveStreams = requiredLiveStreams.filter(
-    (stream) => !presentLiveStreams.has(stream),
+  const coherentProof = coherentPerformanceProof(
+    records,
+    loadProofRecords,
+    requiredStages,
+    requiredLiveStreams,
+    node.wait_for_lifecycle === undefined
+      ? null
+      : String(node.wait_for_lifecycle),
+    node.wait_for_content_variant === undefined
+      ? null
+      : String(node.wait_for_content_variant),
   );
+  const missingLiveStreams = coherentProof.missingLiveStreams;
   const measuredPerpsBootstrapBoundary = perpsBootstrapBoundary(
     records,
     loadProofRecords,
@@ -1088,6 +1466,7 @@ export async function capturePerpsPerformance(input) {
       missingFreshContentVariants.length === 0 &&
       failedFirstFreshDeliveries.length === 0 &&
       missingLiveStreams.length === 0 &&
+      coherentProof.status !== "fail" &&
       (!requirePerpsBootstrapStartBeforeDemand ||
         measuredPerpsBootstrapBoundary.status === "pass") &&
       (!requireCacheBeforeFresh || cacheTakeover.status === "pass")
@@ -1102,6 +1481,9 @@ export async function capturePerpsPerformance(input) {
     missingFreshContentVariants,
     failedFirstFreshDeliveries,
     missingLiveStreams,
+    coherentSurfaceAndLive: coherentProof.status,
+    coherentIdentity: coherentProof.identity,
+    coherentSurfaceSequence: coherentProof.sequence,
     perpsBootstrapStartBeforeDemand: requirePerpsBootstrapStartBeforeDemand
       ? measuredPerpsBootstrapBoundary.status
       : "not_required",
@@ -1120,6 +1502,7 @@ export async function capturePerpsPerformance(input) {
       content.length - offset,
       requiredFreshContentVariants,
       firstFreshDeliveryRequirements,
+      requireCacheBeforeFresh,
     ),
     captureWindow: {
       startedAtEpochMs: state.captureStartedAtEpochMs,
@@ -1149,6 +1532,11 @@ export async function capturePerpsPerformance(input) {
       `Missing required ${STARTUP_MARKER} stages: ${missingStartupStages.join(", ")}.`,
     );
   }
+  if (coherentProof.status === "fail") {
+    throw new Error(
+      `Required ${MARKER} surface stages and live streams did not form one ordered identity-coherent demand tuple.`,
+    );
+  }
   if (
     requirePerpsBootstrapStartBeforeDemand &&
     measuredPerpsBootstrapBoundary.status !== "pass"