@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/profiling/task-latency.js

@@ -0,0 +1,118 @@
+// ============================================================================
+// TaskLatencyHistogram — fixed-bucket histogram for task/tick latency.
+//
+// Updated by wrapping task execution in JS/TS (task-worker + sim tick),
+// QuickJS (eval/callGlobal/tick), and WASM (tick/on_event). Computes
+// p50/p95/p99/max for the ThreadMetrics block. Also retains a small ring
+// of recent samples (name + duration + timestamp) for the flame-graph view.
+// ============================================================================
+const NUM_BUCKETS = 64;
+const MAX_SAMPLE_RING = 128;
+export class TaskLatencyHistogram {
+    buckets;
+    bucketMinUs;
+    bucketMaxUs;
+    count = 0;
+    minUs = Infinity;
+    maxUs = 0;
+    totalUs = 0;
+    // Sample ring for the flame-graph view
+    sampleRing;
+    sampleHead = 0;
+    sampleCount = 0;
+    constructor(bucketMinUs = 0, bucketMaxUs = 300_000) {
+        this.buckets = new Uint32Array(NUM_BUCKETS);
+        this.bucketMinUs = bucketMinUs;
+        this.bucketMaxUs = bucketMaxUs;
+        this.sampleRing = new Array(MAX_SAMPLE_RING);
+    }
+    /** Record a latency sample. */
+    record(durationUs, name = "task", depth = 0) {
+        if (durationUs < 0)
+            durationUs = 0;
+        this.count++;
+        this.totalUs += durationUs;
+        if (durationUs < this.minUs)
+            this.minUs = durationUs;
+        if (durationUs > this.maxUs)
+            this.maxUs = durationUs;
+        // Bucket the value
+        const bucketIdx = this.usToBucket(durationUs);
+        this.buckets[bucketIdx]++;
+        // Push to sample ring
+        const sample = { name, durationUs, ts: performance.now(), depth };
+        this.sampleRing[this.sampleHead] = sample;
+        this.sampleHead = (this.sampleHead + 1) % MAX_SAMPLE_RING;
+        if (this.sampleCount < MAX_SAMPLE_RING)
+            this.sampleCount++;
+    }
+    /** Get the p50/p95/p99/max latency in microseconds. */
+    getPercentiles() {
+        if (this.count === 0)
+            return { p50: 0, p95: 0, p99: 0, max: 0 };
+        const p50Count = Math.floor(this.count * 0.5);
+        const p95Count = Math.floor(this.count * 0.95);
+        const p99Count = Math.floor(this.count * 0.99);
+        let cumulative = 0;
+        let p50 = 0, p95 = 0, p99 = 0;
+        for (let i = 0; i < NUM_BUCKETS; i++) {
+            cumulative += this.buckets[i];
+            if (p50 === 0 && cumulative >= p50Count)
+                p50 = this.bucketToUs(i);
+            if (p95 === 0 && cumulative >= p95Count)
+                p95 = this.bucketToUs(i);
+            if (p99 === 0 && cumulative >= p99Count)
+                p99 = this.bucketToUs(i);
+        }
+        return { p50, p95, p99, max: this.maxUs };
+    }
+    getCount() {
+        return this.count;
+    }
+    getMaxUs() {
+        return this.maxUs;
+    }
+    /** Get recent samples for the flame-graph view (most recent first). */
+    getSamples() {
+        if (this.sampleCount === 0)
+            return [];
+        const result = [];
+        for (let i = 0; i < this.sampleCount; i++) {
+            const idx = (this.sampleHead - 1 - i + MAX_SAMPLE_RING * 2) % MAX_SAMPLE_RING;
+            result.push(this.sampleRing[idx]);
+        }
+        return result;
+    }
+    /** Reset the histogram + samples (e.g. on hot-reload). */
+    reset() {
+        this.buckets.fill(0);
+        this.count = 0;
+        this.minUs = Infinity;
+        this.maxUs = 0;
+        this.totalUs = 0;
+        this.sampleHead = 0;
+        this.sampleCount = 0;
+    }
+    usToBucket(us) {
+        if (us <= this.bucketMinUs)
+            return 0;
+        if (us >= this.bucketMaxUs)
+            return NUM_BUCKETS - 1;
+        // Logarithmic bucketing for better resolution at low latencies
+        const logMin = Math.log(this.bucketMinUs + 1);
+        const logMax = Math.log(this.bucketMaxUs);
+        const logUs = Math.log(us + 1);
+        const frac = (logUs - logMin) / (logMax - logMin);
+        return Math.min(NUM_BUCKETS - 1, Math.max(0, Math.floor(frac * NUM_BUCKETS)));
+    }
+    bucketToUs(idx) {
+        if (idx === 0)
+            return this.bucketMinUs;
+        if (idx === NUM_BUCKETS - 1)
+            return this.bucketMaxUs;
+        const logMin = Math.log(this.bucketMinUs + 1);
+        const logMax = Math.log(this.bucketMaxUs);
+        const logUs = logMin + (idx / NUM_BUCKETS) * (logMax - logMin);
+        return Math.exp(logUs) - 1;
+    }
+}

package/dist/core/src/profiling/thread-metrics.js

@@ -0,0 +1,103 @@
+// ============================================================================
+// ThreadMetricsWriter — writes the ThreadMetrics block to a ProfilingSAB slot
+// each tick. Reads memory from performance.memory / process.memoryUsage /
+// quickjs.memoryUsage / WebAssembly.Memory depending on runtime. CPU time via
+// performance.now() deltas. GC via the existing GCTracker.
+// ============================================================================
+import { GCTracker } from "../telemetry/gc-tracker.js";
+export class ThreadMetricsWriter {
+    writer;
+    opts;
+    tick = 0;
+    lastCpuTimeMs = 0;
+    cpuTimeMs = 0;
+    lastFlushMs = 0;
+    activeWorkMs = 0;
+    frameDurations = [];
+    maxFrameHistory = 60;
+    constructor(writer, opts) {
+        this.writer = writer;
+        this.opts = opts;
+        this.lastFlushMs = performance.now();
+    }
+    /**
+     * Record active work time (e.g. time spent processing a task/message).
+     * This is accumulated between flushes and used to compute true CPU
+     * utilization = workTime / wallClockTime.
+     */
+    recordWork(ms) {
+        if (ms > 0)
+            this.activeWorkMs += ms;
+    }
+    /**
+     * Flush the ThreadMetrics block to the SAB.
+     * Call this each tick (sim workers) or on an interval (non-sim workers).
+     */
+    flush() {
+        this.tick++;
+        const now = performance.now();
+        const wallMs = now - this.lastFlushMs;
+        this.lastFlushMs = now;
+        this.cpuTimeMs += this.activeWorkMs;
+        this.frameDurations.push(wallMs);
+        if (this.frameDurations.length > this.maxFrameHistory)
+            this.frameDurations.shift();
+        // CPU percent = active work time / wall clock time since last flush.
+        // This is true CPU utilization (0% when idle, 100% when fully busy),
+        // not "frame time as % of 60fps budget" which was always ~100% for
+        // interval-based flushes.
+        const cpuPercent = wallMs > 0
+            ? Math.min(100, (this.activeWorkMs / wallMs) * 100)
+            : 0;
+        this.activeWorkMs = 0;
+        // Memory
+        const mem = this.getMemory();
+        // GC stats
+        let gcPauseTotalUs = 0, gcPauseCount = 0, gcPauseMaxUs = 0;
+        if (this.opts.gcTracker && this.opts.gcTracker.isEnabled()) {
+            const gcStats = this.opts.gcTracker.getStats();
+            gcPauseTotalUs = Math.round(gcStats.pauseTotal * 1000); // ms → us
+            gcPauseCount = gcStats.pauseCount;
+            gcPauseMaxUs = Math.round(gcStats.pauseMax * 1000);
+        }
+        // Task latency percentiles
+        let taskLatencyP50Us = 0, taskLatencyP95Us = 0, taskLatencyP99Us = 0, taskLatencyMaxUs = 0;
+        let taskCount = 0;
+        if (this.opts.taskLatency) {
+            const p = this.opts.taskLatency.getPercentiles();
+            taskLatencyP50Us = p.p50;
+            taskLatencyP95Us = p.p95;
+            taskLatencyP99Us = p.p99;
+            taskLatencyMaxUs = p.max;
+            taskCount = this.opts.taskLatency.getCount();
+        }
+        this.writer.writeThreadMetrics({
+            heapUsed: mem.heapUsed,
+            heapTotal: mem.heapTotal,
+            rss: mem.rss,
+            cpuTimeMs: this.cpuTimeMs,
+            cpuPercent,
+            gcPauseTotalUs,
+            gcPauseCount,
+            gcPauseMaxUs,
+            tick: this.tick,
+            taskCount,
+            taskLatencyP50Us,
+            taskLatencyP95Us,
+            taskLatencyP99Us,
+            taskLatencyMaxUs,
+        });
+    }
+    getTick() {
+        return this.tick;
+    }
+    getMemory() {
+        if (this.opts.getHeap) {
+            return this.opts.getHeap();
+        }
+        // Reuse GCTracker.getCurrentMemory() which handles process.memoryUsage
+        // and performance.memory fallbacks.
+        const mem = GCTracker.getCurrentMemory();
+        return { heapUsed: mem.heapUsed, heapTotal: mem.heapTotal, rss: mem.rss };
+    }
+}

package/dist/core/src/profiling/trace-event-writer.js

@@ -0,0 +1,165 @@
+// ============================================================================
+// TraceEventWriter — in-engine Chrome Trace Event format export.
+//
+// Serializes the ProfilingSAB's task/IOPS/GC/event-loop samples to Chrome
+// Trace Event JSON — no host dependency. The resulting .json is viewable
+// in Perfetto UI and Spall.
+//
+// Captures the engine's own instrumentation only (no VM/GPU/driver detail).
+// ============================================================================
+export class TraceEventWriter {
+    events = [];
+    recording = false;
+    startTimeMs = 0;
+    opts;
+    constructor(opts = {}) {
+        this.opts = {
+            includeIops: true,
+            includeWarnings: true,
+            includeGc: true,
+            ...opts,
+        };
+    }
+    isRecording() {
+        return this.recording;
+    }
+    /** Start recording. Clears any previous events. */
+    startRecording() {
+        this.events = [];
+        this.recording = true;
+        this.startTimeMs = performance.now();
+    }
+    /**
+     * Ingest a ProfilingSnapshot. Called each frame while recording.
+     * Converts the snapshot's data into Chrome Trace Event format.
+     */
+    ingestSnapshot(snapshot) {
+        if (!this.recording)
+            return;
+        const tsOffsetUs = (performance.now() - this.startTimeMs) * 1000;
+        snapshot.slots.forEach((slot) => {
+            const pid = slot.slotIndex;
+            const tid = slot.runtime;
+            // Task latency as a complete event per slot
+            const metrics = slot.metrics;
+            if (metrics.taskCount > 0) {
+                this.events.push({
+                    name: "task",
+                    cat: "task",
+                    ph: "X",
+                    ts: tsOffsetUs,
+                    dur: metrics.taskLatencyP95Us,
+                    pid,
+                    tid,
+                    args: {
+                        p50: metrics.taskLatencyP50Us,
+                        p95: metrics.taskLatencyP95Us,
+                        p99: metrics.taskLatencyP99Us,
+                        max: metrics.taskLatencyMaxUs,
+                        count: metrics.taskCount,
+                    },
+                });
+            }
+            // GC pause events
+            if (this.opts.includeGc && metrics.gcPauseCount > 0) {
+                this.events.push({
+                    name: "gc",
+                    cat: "gc",
+                    ph: "X",
+                    ts: tsOffsetUs,
+                    dur: metrics.gcPauseMaxUs,
+                    pid,
+                    tid,
+                    args: {
+                        count: metrics.gcPauseCount,
+                        totalUs: metrics.gcPauseTotalUs,
+                        maxUs: metrics.gcPauseMaxUs,
+                    },
+                });
+            }
+            // Event loop jitter
+            const el = slot.eventLoop;
+            if (el.rafJitterMaxUs > 0) {
+                this.events.push({
+                    name: "raf-jitter",
+                    cat: "event-loop",
+                    ph: "X",
+                    ts: tsOffsetUs,
+                    dur: el.rafJitterMaxUs,
+                    pid,
+                    tid,
+                    args: {
+                        p50: el.rafJitterP50Us,
+                        p95: el.rafJitterP95Us,
+                        max: el.rafJitterMaxUs,
+                        longtaskCount: el.longtaskCount,
+                        longtaskMaxMs: el.longtaskMaxMs,
+                        idleHeadroomMs: el.idleHeadroomMs,
+                    },
+                });
+            }
+            // IOPS records
+            if (this.opts.includeIops) {
+                slot.iopsRecords.forEach((iops) => {
+                    this.events.push(this.iopsToEvent(iops, pid, tid, slot.tagTable));
+                });
+            }
+        });
+        // Warnings as instant events
+        if (this.opts.includeWarnings) {
+            snapshot.warnings.forEach((w) => {
+                this.events.push(this.warningToEvent(w));
+            });
+        }
+    }
+    /** Stop recording and return the Chrome Trace Event JSON. */
+    stopRecording() {
+        this.recording = false;
+        const json = JSON.stringify({ traceEvents: this.events });
+        return {
+            json,
+            bytes: json.length,
+            eventCount: this.events.length,
+        };
+    }
+    iopsToEvent(iops, pid, tid, tagTable) {
+        const storeName = iops.store === 0 ? "opfs" : "idb";
+        const tag = tagTable.get(iops.tagHash) ?? `hash:${iops.tagHash}`;
+        return {
+            name: `iops:${storeName}`,
+            cat: `iops,${storeName}`,
+            ph: "X",
+            ts: iops.ts * 1000, // ms → us
+            dur: iops.latencyUs,
+            pid,
+            tid,
+            args: {
+                op: iops.opKind,
+                tag,
+                bytes: iops.bytes,
+                latencyUs: iops.latencyUs,
+            },
+        };
+    }
+    warningToEvent(w) {
+        const severityNames = ["info", "warn", "error", "critical"];
+        const sev = severityNames[w.severity] ?? "unknown";
+        return {
+            name: `warning:${sev}`,
+            cat: "warning",
+            ph: "i",
+            ts: w.ts * 1000,
+            pid: 0,
+            tid: 0,
+            args: {
+                ruleIdHash: w.ruleIdHash,
+                severity: sev,
+                metricKind: w.metricKind,
+                value: w.value,
+                threshold: w.threshold,
+                workerTag: w.workerTag,
+                autoTraceFired: w.autoTraceFired,
+            },
+        };
+    }
+}

package/dist/core/src/profiling/warnings.js

@@ -0,0 +1,304 @@
+// ============================================================================
+// WarningEngine — multi-level warning-rules engine for the profiling system.
+//
+// Rules fire in two modes:
+//   - Instantaneous (worker-side): checkInstant() is called right after a
+//     metric is recorded (e.g. an IOPS op completes, a tick finishes). Fires
+//     immediately if the threshold is crossed.
+//   - Windowed (renderer-side): checkWindow() is called each frame with the
+//     latest ProfilingSnapshot. Maintains per-rule rolling windows; fires
+//     when the threshold holds for the configured windowMs.
+//
+// Both modes share the same WarningRule descriptor + WarningCallback shape.
+// Cooldown prevents a rule from re-firing within cooldownMs.
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+import { fnv1a32, METRIC_CPU_PERCENT, METRIC_CUSTOM, METRIC_GC_PAUSE, METRIC_GPU_TIME, METRIC_HEAP_PERCENT, METRIC_HEAP_USAGE, METRIC_IOPS_LATENCY, METRIC_LONGTASK, METRIC_RAF_JITTER, METRIC_TASK_LATENCY, METRIC_TICK_LATENCY, SEVERITY_CRITICAL, SEVERITY_ERROR, SEVERITY_INFO, SEVERITY_WARN, } from "./profiling-sab.js";
+const log = createLogger();
+export { SEVERITY_CRITICAL, SEVERITY_ERROR, SEVERITY_INFO, SEVERITY_WARN };
+export { METRIC_CPU_PERCENT, METRIC_CUSTOM, METRIC_GC_PAUSE, METRIC_GPU_TIME, METRIC_HEAP_PERCENT, METRIC_HEAP_USAGE, METRIC_IOPS_LATENCY, METRIC_LONGTASK, METRIC_RAF_JITTER, METRIC_TASK_LATENCY, METRIC_TICK_LATENCY };
+/**
+ * Warning-rules engine. Constructed per-realm (one in each worker via the
+ * prelude, one on the renderer via the ProfilingBridge).
+ */
+export class WarningEngine {
+    rules = new Map();
+    states = new Map();
+    callbacks = [];
+    writer = null;
+    workerTag = 0;
+    runtime = 0;
+    autoTraceAvailable = false;
+    /**
+     * @param writer Optional ProfilingSABWriter for pushing WarningRecords to
+     *   the SAB warning ring. If null, warnings are only delivered via callbacks
+     *   (useful for the renderer-side engine where the bridge handles SAB writing).
+     */
+    constructor(writer) {
+        this.writer = writer ?? null;
+    }
+    setWriter(writer) {
+        this.writer = writer;
+    }
+    setWorkerTag(tag) {
+        this.workerTag = tag;
+    }
+    setRuntime(runtime) {
+        this.runtime = runtime;
+    }
+    setAutoTraceAvailable(available) {
+        this.autoTraceAvailable = available;
+    }
+    addRule(rule) {
+        this.rules.set(rule.id, rule);
+        if (!this.states.has(rule.id)) {
+            this.states.set(rule.id, { lastFiredMs: -Infinity, windowStartMs: null });
+        }
+    }
+    removeRule(id) {
+        this.rules.delete(id);
+        this.states.delete(id);
+    }
+    clearRules() {
+        this.rules.clear();
+        this.states.clear();
+    }
+    getRules() {
+        return Array.from(this.rules.values());
+    }
+    onWarning(cb) {
+        this.callbacks.push(cb);
+        return () => {
+            const idx = this.callbacks.indexOf(cb);
+            if (idx >= 0)
+                this.callbacks.splice(idx, 1);
+        };
+    }
+    clearCallbacks() {
+        this.callbacks = [];
+    }
+    /**
+     * Evaluate an instantaneous rule (worker-side).
+     * Called right after a metric is recorded.
+     */
+    checkInstant(metric, value, extra) {
+        const now = performance.now();
+        for (const rule of this.rules.values()) {
+            if (rule.metric !== metric)
+                continue;
+            if (rule.sustained && rule.windowMs)
+                continue; // windowed rules are handled by checkWindow
+            if (!this.compare(value, rule.compare, rule.threshold)) {
+                // Reset window state if the condition is false
+                const state = this.states.get(rule.id);
+                if (state)
+                    state.windowStartMs = null;
+                continue;
+            }
+            this.tryFire(rule, value, now, extra);
+        }
+    }
+    /**
+     * Evaluate windowed rules against the latest snapshot (renderer-side).
+     * Called each frame by the ProfilingBridge.
+     */
+    checkWindow(getMetricValue) {
+        const now = performance.now();
+        for (const rule of this.rules.values()) {
+            if (!rule.sustained || !rule.windowMs)
+                continue; // only windowed rules
+            const value = getMetricValue(rule.metric);
+            const state = this.states.get(rule.id);
+            const conditionMet = this.compare(value, rule.compare, rule.threshold);
+            if (conditionMet) {
+                if (state.windowStartMs === null) {
+                    state.windowStartMs = now;
+                }
+                const elapsed = now - state.windowStartMs;
+                if (elapsed >= rule.windowMs) {
+                    this.tryFire(rule, value, now);
+                }
+            }
+            else {
+                state.windowStartMs = null;
+            }
+        }
+    }
+    tryFire(rule, value, now, extra) {
+        const state = this.states.get(rule.id);
+        const cooldown = rule.cooldownMs ?? 5000;
+        if (now - state.lastFiredMs < cooldown)
+            return;
+        state.lastFiredMs = now;
+        const ruleIdHash = fnv1a32(rule.id);
+        const record = {
+            ruleId: rule.id,
+            ruleIdHash,
+            severity: rule.severity,
+            metricKind: rule.metric,
+            value,
+            threshold: rule.threshold,
+            workerTag: this.workerTag,
+            ts: now,
+            autoTraceFired: false,
+        };
+        const ctx = {
+            workerTag: this.workerTag,
+            runtime: this.runtime,
+            rule,
+            autoTraceAvailable: this.autoTraceAvailable,
+            tag: extra?.tag,
+        };
+        // Push to SAB warning ring (if writer is set)
+        if (this.writer) {
+            this.writer.pushWarningRecord({
+                ruleIdHash,
+                severity: rule.severity,
+                metricKind: rule.metric,
+                value,
+                threshold: rule.threshold,
+                workerTag: this.workerTag,
+                ts: now,
+                autoTraceFired: false, // the bridge sets this when auto-trace actually fires
+            });
+        }
+        // Invoke callbacks
+        this.callbacks.forEach((cb) => {
+            try {
+                cb(record, ctx);
+            }
+            catch (err) {
+                // Don't let a callback error stop other callbacks
+                log.error("warning-engine", `callback error for rule "${rule.id}": ${err}`);
+            }
+        });
+    }
+    compare(value, op, threshold) {
+        switch (op) {
+            case ">": return value > threshold;
+            case ">=": return value >= threshold;
+            case "<": return value < threshold;
+            default: return false;
+        }
+    }
+}
+// ─── Default warning rules ──────────────────────────────────────────────────
+/**
+ * Default warning rules registered by the prelude (workers) and initDevTools
+ * (renderer) unless `defaultWarningRules: false`.
+ */
+export const DEFAULT_WORKER_WARNING_RULES = [
+    {
+        id: "dd:tick-slow",
+        severity: SEVERITY_WARN,
+        metric: METRIC_TICK_LATENCY,
+        compare: ">",
+        threshold: 50_000, // 50ms in us
+        cooldownMs: 5000,
+        description: "A sim tick took >50ms",
+    },
+    {
+        id: "dd:tick-very-slow",
+        severity: SEVERITY_ERROR,
+        metric: METRIC_TICK_LATENCY,
+        compare: ">",
+        threshold: 200_000, // 200ms in us
+        cooldownMs: 5000,
+        autoTrace: { preset: "perf", durationMs: 3000, source: "in-engine" },
+        description: "A sim tick took >200ms — auto-trace fired",
+    },
+    {
+        id: "dd:iops-slow",
+        severity: SEVERITY_WARN,
+        metric: METRIC_IOPS_LATENCY,
+        compare: ">",
+        threshold: 500_000, // 500ms in us
+        cooldownMs: 5000,
+        description: "An IOPS op took >500ms",
+    },
+    {
+        id: "dd:gc-pause-long",
+        severity: SEVERITY_WARN,
+        metric: METRIC_GC_PAUSE,
+        compare: ">",
+        threshold: 50_000, // 50ms in us
+        cooldownMs: 5000,
+        description: "A GC pause >50ms",
+    },
+    {
+        id: "dd:raf-jitter-high",
+        severity: SEVERITY_WARN,
+        metric: METRIC_RAF_JITTER,
+        compare: ">",
+        threshold: 5_000, // 5ms in us
+        cooldownMs: 10000,
+        description: "rAF jitter >5ms",
+    },
+    {
+        id: "dd:longtask",
+        severity: SEVERITY_WARN,
+        metric: METRIC_LONGTASK,
+        compare: ">",
+        threshold: 50_000, // 50ms in us
+        cooldownMs: 5000,
+        description: "A long task >50ms",
+    },
+];
+export const DEFAULT_RENDERER_WARNING_RULES = [
+    {
+        id: "dd:heap-high",
+        severity: SEVERITY_WARN,
+        metric: METRIC_HEAP_PERCENT,
+        compare: ">",
+        threshold: 80,
+        sustained: true,
+        windowMs: 3000,
+        cooldownMs: 10000,
+        description: "Heap usage >80% sustained for 3s",
+    },
+    {
+        id: "dd:heap-critical",
+        severity: SEVERITY_CRITICAL,
+        metric: METRIC_HEAP_PERCENT,
+        compare: ">",
+        threshold: 95,
+        sustained: true,
+        windowMs: 2000,
+        cooldownMs: 10000,
+        autoTrace: { preset: "memory", durationMs: 2000, source: "in-engine" },
+        description: "Heap usage >95% sustained for 2s — auto-trace fired",
+    },
+    {
+        id: "dd:task-p95-high",
+        severity: SEVERITY_WARN,
+        metric: METRIC_TASK_LATENCY,
+        compare: ">",
+        threshold: 100_000, // 100ms in us
+        sustained: true,
+        windowMs: 5000,
+        cooldownMs: 10000,
+        description: "Task p95 latency >100ms sustained for 5s",
+    },
+    {
+        id: "dd:raf-jitter-sustained",
+        severity: SEVERITY_WARN,
+        metric: METRIC_RAF_JITTER,
+        compare: ">",
+        threshold: 5_000, // 5ms in us
+        sustained: true,
+        windowMs: 3000,
+        cooldownMs: 10000,
+        description: "rAF jitter >5ms sustained for 3s",
+    },
+    {
+        id: "dd:gpu-time-high",
+        severity: SEVERITY_WARN,
+        metric: METRIC_GPU_TIME,
+        compare: ">",
+        threshold: 16_000, // 16ms in us
+        sustained: true,
+        windowMs: 2000,
+        cooldownMs: 10000,
+        description: "GPU time >16ms sustained for 2s",
+    },
+];