| 1 | import { createHash } from "node:crypto"; |
| 2 | import { execFileSync } from "node:child_process"; |
| 3 | import { readdirSync, readFileSync } from "node:fs"; |
| 4 | import path from "node:path"; |
| 5 | import { boundedParserWorker, domListenerCount } from "./app-memory-workers.mjs"; |
| 6 | |
| 7 | export function buildIdentity(frontendDir) { |
| 8 | const hash = createHash("sha256"); |
| 9 | function visit(directory) { |
| 10 | for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) { |
| 11 | const file = path.join(directory, entry.name); |
| 12 | if (entry.isDirectory()) visit(file); |
| 13 | else hash.update(path.relative(frontendDir, file)).update(readFileSync(file)); |
| 14 | } |
| 15 | } |
| 16 | visit(path.join(frontendDir, "dist")); |
| 17 | const git = (...args) => execFileSync("git", args, { cwd: frontendDir, encoding: "utf8" }).trim(); |
| 18 | const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z", "--", "."], { cwd: frontendDir, encoding: "utf8" }).split("\0").filter(Boolean).sort(); |
| 19 | const untrackedHash = createHash("sha256"); |
| 20 | for (const file of untracked) untrackedHash.update(file).update("\0").update(readFileSync(path.join(frontendDir, file))).update("\0"); |
| 21 | return { |
| 22 | sourceSHA: git("rev-parse", "HEAD"), |
| 23 | trackedDiffSHA256: createHash("sha256").update(git("diff", "HEAD", "--", ".")).digest("hex"), |
| 24 | untrackedSourceSHA256: untrackedHash.digest("hex"), |
| 25 | sourceStatus: git("status", "--porcelain", "--", "."), |
| 26 | buildSHA256: hash.digest("hex"), |
| 27 | node: process.version, platform: process.platform, arch: process.arch, |
| 28 | }; |
| 29 | } |
| 30 | |
| 31 | // IDs, not count deltas: an increasing population can hide behind simultaneous GC. |
| 32 | export function retainedCohorts(samples) { |
| 33 | const firstSeen = new Map(); |
| 34 | return samples.map((sample, index) => { |
| 35 | const ids = sample.lifecycle.liveRenderTokenIds; |
| 36 | for (const id of ids) if (!firstSeen.has(id)) firstSeen.set(id, index); |
| 37 | return { |
| 38 | phase: sample.phase, roundTrips: sample.roundTrips, |
| 39 | survivorsFromBaseline: ids.filter(id => firstSeen.get(id) === 0), |
| 40 | // Two later observations after completed round trips; not a whole-App count budget. |
| 41 | retainedPostBaseline: ids.filter(id => firstSeen.get(id) > 0 && firstSeen.get(id) < index - 1), |
| 42 | }; |
| 43 | }); |
| 44 | } |
| 45 | |
| 46 | export function evidenceIntegrity(samples) { |
| 47 | return samples.length > 0 && samples.every(({ lifecycle }) => ( |
| 48 | Array.isArray(lifecycle.liveRenderTokenIds) |
| 49 | && new Set(lifecycle.liveRenderTokenIds).size === lifecycle.liveRenderTokenIds.length |
| 50 | && lifecycle.liveRenderTokenIds.length === lifecycle.liveRenderTokens |
| 51 | && lifecycle.overflow === false && lifecycle.invariantViolations === 0 |
| 52 | && lifecycle.activeOperations >= 0 && lifecycle.activeSubscriptions >= 0 |
| 53 | )); |
| 54 | } |
| 55 | |
| 56 | // Counter stability is a screening result, not heap-retainer attribution. |
| 57 | // Weak refs observe only instrumented tokens. They cannot explain survivors |
| 58 | // outside that cohort, compiled-code growth, or the mainline control delta, |
| 59 | // so heap-retainer and control evidence stays an offline attribution duty |
| 60 | // that the automated gate can never discharge by itself. |
| 61 | export const OFFLINE_ATTRIBUTION_REASON = "heap-retainer-and-control-evidence-required"; |
| 62 | |
| 63 | // A counter excursion that fully returns to the warmed baseline is a recorded |
| 64 | // observation, not a leak signal: the objects were provably freed. Real soak |
| 65 | // data shows such blips at phase transitions (e.g. 614 listeners settling |
| 66 | // back to 512). Only a displaced final tail is persistent drift. |
| 67 | export const TRANSIENT_EXCURSION_REASON = "transient-counter-excursion"; |
| 68 | |
| 69 | // A single early baseline reading can sit above the resting value while layout |
| 70 | // cleanup still owns listeners. Every later reading then looks displaced, which |
| 71 | // the gate would misreport as persistent drift. An unsettled baseline is |
| 72 | // reported as its own blocker instead of being judged as displacement. |
| 73 | export const BASELINE_NOT_SETTLED_REASON = "baseline-not-settled"; |
| 74 | |
| 75 | // Reasons the automated gate must block on. Observations (the offline |
| 76 | // attribution duty, fully-recovered excursions) are recorded on every report |
| 77 | // but are not screening failures. |
| 78 | export function screeningBlockers(reasons) { |
| 79 | return reasons.filter((reason) => reason !== OFFLINE_ATTRIBUTION_REASON && reason !== TRANSIENT_EXCURSION_REASON); |
| 80 | } |
| 81 | |
| 82 | // The gate blocks on retention-shaped drift: a final population above the |
| 83 | // warmed baseline, or an unsettled-baseline tail that is still growing. |
| 84 | // A final population below baseline is released capacity, not retention. |
| 85 | // Intermediate excursions are kept as observations so they still get an |
| 86 | // offline explanation. When the bench ends with an explicit "settled" |
| 87 | // resting-state sample, that sample is the authoritative tail. |
| 88 | function counterDriftReason(values, phases, baselineStable = true) { |
| 89 | const baseline = values[0]; |
| 90 | const final = values.at(-1); |
| 91 | const settledTail = phases.at(-1) === "settled"; |
| 92 | if (baselineStable && final > baseline) return "persistent"; |
| 93 | if (!baselineStable && !settledTail) { |
| 94 | const tail = values.slice(1).slice(-3); |
| 95 | if (tail.length > 1 && tail.every((value, index) => index === 0 || value >= tail[index - 1]) |
| 96 | && tail.at(-1) > tail[0]) return "persistent"; |
| 97 | } |
| 98 | return values.some((value) => value !== baseline) ? "transient" : null; |
| 99 | } |
| 100 | |
| 101 | export function attributeRetention(samples, cohorts = retainedCohorts(samples)) { |
| 102 | if (!evidenceIntegrity(samples) || samples.length < 2) return { status: "needs-attribution", reasons: ["invalid-evidence"] }; |
| 103 | const retained = cohorts.some((cohort) => cohort.retainedPostBaseline.length > 0); |
| 104 | const nativeCountersValid = samples.every(({ dom }) => |
| 105 | [dom?.nodes, dom?.jsEventListeners].every(value => Number.isSafeInteger(value) && value >= 0)); |
| 106 | const released = samples.every((sample) => sample.lifecycle.activeOperations === 0); |
| 107 | const phases = samples.map((sample) => sample.phase); |
| 108 | const baselineStable = samples[0]?.baselineStable !== false; |
| 109 | const reasons = []; |
| 110 | if (retained) reasons.push("persistent-render-cohort"); |
| 111 | if (samples.some(sample => !boundedParserWorker(sample) || domListenerCount(sample) < 0)) reasons.push("worker-population-drift"); |
| 112 | if (!nativeCountersValid) reasons.push("invalid-native-counters"); |
| 113 | if (!baselineStable) reasons.push(BASELINE_NOT_SETTLED_REASON); |
| 114 | if (nativeCountersValid) { |
| 115 | const nodeDrift = counterDriftReason(samples.map((sample) => sample.dom.nodes), phases, baselineStable); |
| 116 | const listenerDrift = counterDriftReason(samples.map(domListenerCount), phases, baselineStable); |
| 117 | if (nodeDrift === "persistent" || listenerDrift === "persistent") reasons.push("post-gc-dom-or-listener-drift"); |
| 118 | else if (nodeDrift === "transient" || listenerDrift === "transient") reasons.push(TRANSIENT_EXCURSION_REASON); |
| 119 | } |
| 120 | const subscriptionDrift = counterDriftReason(samples.map((sample) => sample.lifecycle.activeSubscriptions), phases); |
| 121 | if (subscriptionDrift === "persistent") reasons.push("subscription-population-drift"); |
| 122 | else if (subscriptionDrift === "transient") reasons.push(TRANSIENT_EXCURSION_REASON); |
| 123 | if (!released) reasons.push("active-operations"); |
| 124 | reasons.push(OFFLINE_ATTRIBUTION_REASON); |
| 125 | return { status: "needs-attribution", reasons: [...new Set(reasons)] }; |
| 126 | } |
| 127 | |
| 128 | // CDP's DOM counter includes attached and detached nodes. Only the heap's |
| 129 | // detachedness field can label an object as detached; unknown stays unknown. |
| 130 | export function summarizeHeap(snapshot) { |
| 131 | const { node_fields: fields, node_types: types } = snapshot.snapshot.meta; |
| 132 | const width = fields.length; |
| 133 | const at = Object.fromEntries(fields.map((field, index) => [field, index])); |
| 134 | const categories = {}; |
| 135 | const detached = {}; |
| 136 | for (let offset = 0; offset < snapshot.nodes.length; offset += width) { |
| 137 | const type = types[at.type][snapshot.nodes[offset + at.type]]; |
| 138 | const category = categories[type] ??= { count: 0, selfBytes: 0 }; |
| 139 | category.count++; |
| 140 | category.selfBytes += snapshot.nodes[offset + at.self_size]; |
| 141 | if (at.detachedness !== undefined && snapshot.nodes[offset + at.detachedness] === 2) { |
| 142 | const name = snapshot.strings[snapshot.nodes[offset + at.name]]; |
| 143 | const entry = detached[name] ??= { count: 0, selfBytes: 0, ids: [] }; |
| 144 | entry.count++; |
| 145 | entry.selfBytes += snapshot.nodes[offset + at.self_size]; |
| 146 | entry.ids.push(snapshot.nodes[offset + at.id]); |
| 147 | } |
| 148 | } |
| 149 | return { categories, detached, detachednessAvailable: at.detachedness !== undefined }; |
| 150 | } |
| 151 |